/[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 1496 by frank,
Tue Jul 29 12:07:13 2003 UTC
+revision 2670 by frank,
Thu Sep  8 16:44:26 2005 UTC
 Line 2
  <!DOCTYPE book
          PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
          "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
-     [<!ENTITY imgscale "70">]>
+     [<!ENTITY imgscale "60">]>
  <!-- $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>
+       <year>2003, 2004, 2005</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.0.0</revnumber>
+         <date>22-Jan-2004</date>
+         <revremark>
+                         Corresponds to Thuban 1.0.0.
+                         New: Installation instructions for Win32.
+                 </revremark>
+      </revision>
+      <revision>
+         <revnumber>1.0pre3</revnumber>
+         <date>04-Dec-2003</date>
+         <revremark>
+                         Corresponds to Thuban 1.0rc1.
+                         New: I18n, right button legend menu, EPSG projectons,
+             PostGIS support.
+                 </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
+     Its development had been started 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
+     written mainly in Python and uses the wxWidgets (former 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 40
+Line 83
      </para>
      <para>
      Thuban arranges a session in a hierarchy. A session contains a map which
-     consists of layers. Each layer represents one kind of data set. For
+     consists of layers. Each layer represents a data set. For
      instance, there may be a layer for roads and another layer for buildings.
      These layers can either be vector shapes or images.
      </para>
-Line 48
+Line 91
          <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>
+         <para>
+         Required:
+         <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>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>
+         Optional:
+         <itemizedlist>
+             <listitem><para>GDAL 1.1.8
+                         (<literal>http://www.remotesensing.org/gdal/</literal>)
+                         </para></listitem>
+             <listitem><para>psycopg 1.0.8
+                         (<literal>http://initd.org/software/psycopg</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> <!-- Intro - Installation - RPM-->
+                 <section><title>Win32 Systems</title>
+                 <para>
+                         A common installation package of Thuban for Win32
+                         systems is available from the Thuban website download
+                         section. This installation package is configured for
+                         displaying file based vector data (Shapefiles). For the
+                         display of raster data or the connection to spatial
+                         databases additional steps are needed.
+                 </para>
+                 <para>
+                         The required Python packages are listed and linked on
+                         the download page as well.  If you don't have Python
+                         installed already, download the packages for Python,
+                         wxPython for Python and the SQLite Python Libraries as
+                         well as the Thuban package. Install all four packages
+                         in the order: Python, wxPython, SQLite, Thuban. Follow
+                         the installation instructions provided by the seperate
+                         setups. The Thuban installation package will add an
+                         entry in the menu folder you configured.
+                 </para>
+                 <section><title>Raster Data: Installation of GDAL</title>
+                 <para>
+                         Enabling the raster data features of Thuban is
+                         straight forward. For the examples we assume that
+                         Thuban has been installed under
+                         <literal>C:\Thuban</literal>:
+                         <itemizedlist>
+                         <listitem>
+                         <para>
+                         Download the zip-archive <ulink
+                         url="ftp://intevation.de/thuban/win2k/gdal-win2k.zip"
+                         >gdal-win2k</ulink>.
+                         </para></listitem>
+                         <listitem><para>Extract the archive (e.g. with
+                         <ulink
+                         url="http://www.info-zip.org/pub/infozip/WiZ.html"
+                         >WiZ (InfoZip)</ulink>) into the
+                         <literal>C:\Thuban\Lib</literal>
+                         directory of your Thuban installation.
+                         </para>
+                         </listitem>
+                         <listitem>
+                         <para>
+                         Extent the <varname>PYTHONPATH</varname>
+                         environment variable (in your Windows Control Panel)
+                         to make the new libraries available for Thuban.
+                         <programlisting>
+ %PYTHONPATH%;C:\Thuban\Lib\gdal;C:\Thuban\Lib\gdal\pymod
+                         </programlisting>
+                         </para>
+                         </listitem>
+                         <listitem>
+                         <para>
+                         Extent also the <varname>PATH</varname>
+                         environment variable accordingly:
+                         <programlisting>
+ %PATH%;C:\Thuban\Lib\gdal
+                         </programlisting>
+                         </para>
+                         </listitem>
+                         </itemizedlist>
+                         After this installation steps Thuban is ready to
+                         display raster data (e.g. the
+                         <literal>island.tif</literal> from the Iceland Demo
+                         data set.
+                 </para>
+                 </section> <!-- Win32: GDAL-->
+                 <section><title>Working with PostGIS: Installation of PsycoPG</title>
+                 <para>
+                         To access PostgreSQL/PostGIS spatial databases with
+                         Thuban you have to install the PsycoPG package for
+                         Windows:
+                         <itemizedlist>
+                         <listitem>
+                         <para>
+                         Download the zip-archive
+                         <ulink
+                                 url="http://stickpeople.com/projects/python/win-psycopg/win-psycopg22.zip"
+                         >win-psycopg22.zip</ulink>.
+                         </para>
+                         </listitem>
+                         <listitem>
+                         <para>
+                         Extract the zip-archive into a directory either already
+                         in your <varname>PYTHONPATH</varname> or extent your
+                         <varname>PYTHONPATH</varname> variable to the directory
+                         you have extracted the archive to.
+                         </para>
+                         </listitem>
+                         </itemizedlist>
+                         For installation and maintenance of spatial databases
+                         we refer to the  <ulink
+                         url="http://postgis.refractions.net"
+                         >PostGIS Homepage</ulink>.
+                 </para>
+                 </section> <!-- Win32: PsycoPG-->
+                 </section> <!-- Intro - Installation - Win32 -->
          </section>
+         <section><title>Internationalization</title>
+         <para>
+         Thuban is implemented with internationalization support. So far Thuban
+         is translated by volunteers to the following languages (apart from its
+         main language: English):
+         <itemizedlist>
+             <listitem><para>French</para></listitem>
+             <listitem><para>German</para></listitem>
+             <listitem><para>Italian</para></listitem>
+                 <listitem><para>Portuguese (Brazilian)</para></listitem>
+             <listitem><para>Russian</para></listitem>
+             <listitem><para>Spanish</para></listitem>
+         </itemizedlist>
+         </para>
+         <para>
+         To use internationalization under POSIX systems (like GNU/Linux)
+         you have to set the environment variable LC_ALL accordingly (e.g.
+         LC_ALL=fr_FR for the french language support). Please check your
+         systems documentation for details and supported settings.
+         Specifiying LC_ALL on the command line while launching thuban
+         allows appication specific language settings:
+         </para>
+         <programlisting>
+         LC_ALL=fr_FR thuban.py
+         </programlisting>
+         <para>
+         MS Windows users have to specify the language to be used via the control
+         bar (which effects all applications).
+         </para>
+         </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" scale="&imgscale;"/> </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 121
+Line 484
          If a session is already loaded and has been modified without
          being saved a prompt will ask if the current session should
          be saved. A new session consists of an empty map with no
-         layers and no tables.
+         layers, no tables and no projection.
          </para>
          </section>
-Line 135
+Line 498
          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.
+                 </para>
+                 <para>
          If a session is already loaded and has been modified without
          being saved a prompt will ask if the current session should
          be saved.
          </para>
+                 <para>
+                 Thuban provides a path recovery feature: If a (shape) file referenced
+                 in a Thuban session cannot be found at the specified location, the user
+                 is prompted a file dialog. Here a new location can be selected for the
+                 currents layer data source. Cancelling the dialog removes the layer
+                 from the session. If a new location has been selected, Thuban checks
+                 this again, if further layers data sources are missing. The user is
+                 informed about this and can accept or cancel the suggestion.
+         </para>
          </section>
          <section><title>Saving a Session</title>
-Line 148
+Line 523
          <menuchoice>
          <guimenu>File</guimenu>
          <guimenuitem>Save Session</guimenuitem>
-         </menuchoice>. A dialog box will open allowing the user to browse
+         </menuchoice>.
+                 In the case the session is not a new and unsaved one,
+                 the corresponding file is updated with the current session
+                 data.
+                 In the case the current session is a new one and yet unsaved
+                 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
-Line 159
+Line 539
          <section><title>The Session Info-Tree</title>
          <para>
-         <screenshot>
+         <figure>
-         <screeninfo>Session Info Tree</screeninfo>
+         <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>
-         <textobject><phrase>Session Info Tree</phrase></textobject>
-         <caption><para>Session Info Tree</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          <para>
          The session info-tree is primarily intended for developers working
-Line 209
+Line 587
          <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 three types of layers that can be added to a map:
+         Shape layers, database layers
          and image layers. Shape layers are stored in Shapefile format, a
-         standard file format for storing geographic objects. These
+         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,
+         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>
+         <itemizedlist>
+         <listitem>
+         <para>
          Shape layers can be added to the map with
          <menuchoice>
          <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 shape file or database file is selected.
+                 selection. However, if you switch to display all files and select one
-         </para>
+                 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>
+         </listitem>
+         <listitem>
+         <para>Database layers can be added to the map with
+         <menuchoice>
+         <guimenu>Map</guimenu>
+         <guimenuitem>Add Database Layer</guimenuitem>
+         </menuchoice>.
+         A dialog with two lists is opened. The left list displays all
+         database connections currently open for the session. You can retrieve
+         a list of available layers from the selected database which is
+         displayed on the right hand. From this list one layer can be selected,
+         the dialog is closed afterwards.
+         </para>
+         <para>
+         See appendix ``Working with PostGIS'' for details.
+         </para>
+         </listitem>
+         <listitem>
          <para>
          Image layers can be added to the map with
          <menuchoice>
-Line 240
+Line 647
          or in another file. If geographic information cannot be found, Thuban
          will report an error.
          </para>
+         </listitem>
+         </itemizedlist>
          </section>
          <section><title>Navigation</title>
-Line 248
+Line 657
          the tool bar or from the
          <menuchoice><guimenu>Map</guimenu></menuchoice> menu.
          </para>
+         <itemizedlist>
+         <listitem>
          <para>
          The ZoomIn tool
          <inlinemediaobject>
-Line 261
+Line 672
          </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
+         was clicked. Clicking and dragging selects a region that will be
          enlarged to fit the window.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The ZoomOut tool
          <inlinemediaobject>
-Line 280
+Line 693
          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>
-Line 293
+Line 708
          </inlinemediaobject>
          allows the user to move the map around by clicking and dragging.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The Full Extent tool
          <inlinemediaobject>
-Line 306
+Line 723
          </inlinemediaobject>
          rescales the viewable region so that the entire map is visible.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The Full Layer Extent tool
          <inlinemediaobject>
-Line 321
+Line 740
          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>
-Line 335
+Line 756
          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 353
+Line 779
          </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>
-Line 404
+Line 831
          <menuchoice><guimenu>Map</guimenu></menuchoice>.
          </para>
+         <itemizedlist>
+         <listitem>
          <para>
          The Move Layer to Top tool
          <inlinemediaobject>
-Line 416
+Line 845
          <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
-Line 429
+Line 860
          <textobject> <phrase>Move Layer Up</phrase> </textobject>
          </inlinemediaobject> raises the selected layer one level.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The Move Layer Down tool
-Line 443
+Line 876
          </inlinemediaobject> lowers the selected layer one level.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The Move Layer to Bottom tool
          <inlinemediaobject>
-Line 456
+Line 891
          </inlinemediaobject> lowers the selected layer to the bottom of the map.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The Visible tool
          <inlinemediaobject>
-Line 470
+Line 907
          hidden.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The Invisible tool
          <inlinemediaobject>
-Line 483
+Line 922
          </inlinemediaobject> hides the selected layer in the map.
          </para>
+         </listitem>
+         <listitem>
          <para>
          The Properties tool
          <inlinemediaobject>
-Line 497
+Line 938
          Double-clicking on a layer or a group of a layer will open the
          properties dialog for that layer.
          </para>
+         </listitem>
+         </itemizedlist>
+         <para>
+         The most used layer related actions are also available from a
+         popup menu. It is raised when a layer is clicked with the right mouse
+         button.
+         </para>
+         <para>
+         <figure>
+         <title>Layer Popup Menu</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/3_5_popup_menu.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/3_5_popup_menu.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </para>
+         <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>
-Line 507
+Line 972
          <menuchoice>
          <guimenu>Map</guimenu>
          <guimenuitem>Export</guimenuitem>
-         </menuchoice>. Under other platforms this option is not available.
+         </menuchoice> for use in reports, presentations, or further
-         Clicking this menu item open a file selection dialog that lets the
+         modification. The current map view, legend, and, if available,
-         user select a location to export the map.
+         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>
-Line 519
+Line 986
          <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. This dialog will differ depending
+         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>
-Line 533
+Line 1001
          <section><title>Types of Layers</title>
          <para>
-         There are two types of layers supported by Thuban: shape layers and
+         There are three types of layers supported by Thuban: shape layers,
+         database 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. Database layers are similar
+         to shape layers but loaded from a database instead of the file system.
+         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
-Line 544
+Line 1015
          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>
-Line 554
+Line 1031
          <guimenu>Layer</guimenu>
          <guimenuitem>Properties</guimenuitem>
          </menuchoice> opens a dialog that displays a layer's properties.
-         All layers have a title and it can be modified in the text field
+         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>
-         <screenshot>
+         <figure>
-         <screeninfo>Properties Window</screeninfo>
+         <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>
-         <textobject><phrase>Properties Window</phrase></textobject>
-         <caption><para>The Properties Window for a Shape Layer</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          <para>
-         <screenshot>
+         <figure>
-         <screeninfo>Properties Window</screeninfo>
+         <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>
-         <textobject><phrase>Properties Window</phrase></textobject>
-         <caption><para>The Properties Window for an Image Layer</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          </section>
-Line 646
+Line 1119
      <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 if no other group matches.
+     layer, regardless of its attributes, will match this group if no other
+     group matches.
      </para>
          <section><title>Editing Classifications</title>
-Line 664
+Line 1138
          button.
          </para>
          <para>
-         <screenshot>
+         To apply the changes to the map the user can click
-         <screeninfo>Properties Window</screeninfo>
+         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>
-         <textobject><phrase>Properties Window</phrase></textobject>
-         <caption><para>The Properties Window with Classifications</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          <para>
          The order of the groups in the classification is significant
-Line 738
+Line 1222
          <section><title>Generating Classes</title>
          <para>
-         <screenshot>
+         <figure>
-         <screeninfo>Generate Class</screeninfo>
+         <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>
-         <textobject><phrase>Generate Class</phrase></textobject>
-         <caption><para>The Generate Classifications Dialog</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          <para>
          Creating a classification by hand can be tedious.
-Line 756
+Line 1238
          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, Unique Distribution, and Quantiles. Some options
+         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>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 779
+Line 1273
          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 of items
-         in the input set. For example, by specifying five groups Thuban will
+         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>
-Line 815
+Line 1330
      <guimenu>Layer</guimenu>
      <guimenuitem>Projection</guimenuitem>
      </menuchoice>.
-     <screenshot>
+     <figure>
-     <screeninfo>Projection Window</screeninfo>
+     <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>
-     <textobject><phrase>Projection Window</phrase></textobject>
-     <caption><para>The Projection Window</para></caption>
      </mediaobject>
-     </screenshot>
+     </figure>
+     </para>
+     <para>
+     Thuban is distributed with a sample collection of projections and the
+     set of coordinate systems as used by the EPSG
+     (European Petroleum Survey Group). This quite large set is only displayed
+     if activated by the according checkbox. The set falls into two parts:
+     deprecated lists all projections which are no longer part of the
+     EPSG data base.
      </para>
      <para>
-     Thuban is distributed with a sample collection of projections. The
+          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.
-Line 855
+Line 1376
          <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>
-Line 881
+Line 1414
      <section><title>Table View</title>
          <para>
-         <screenshot>
+         <figure>
-         <screeninfo>Table View</screeninfo>
+         <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>
-         <textobject><phrase>Table View</phrase></textobject>
-         <caption><para>The Table View</para></caption>
          </mediaobject>
-         </screenshot>
+         </figure>
          </para>
          <para>
          Thuban provides a standard dialog to display table contents, the
-         Table View. The view falls has five sections: The title, selections,
+         Table View. The view has five sections: The title, selections,
          the table grid, export functions, and the status bar.
          </para>
          <para>
-Line 906
+Line 1437
          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_inhabitant <  bikes_per_inhabitant" (note that the field names
+         <literal>cars_per_inhabitant < bikes_per_inhabitant</literal>
-         are only explanatory, the 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
          a previously selected set of records or by adding the results of a
-Line 917
+Line 1448
          earlier results.
          </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>
-Line 1010
+Line 1541
          <section><title>Join</title>
              <para>
-             <screenshot>
+             <figure>
-             <screeninfo>Join Tables</screeninfo>
+             <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>
-             <textobject><phrase>Join Tables</phrase></textobject>
-             <caption><para>The Join Tables Dialog</para></caption>
              </mediaobject>
-             </screenshot>
+             </figure>
              </para>
              <para>
              The
-Line 1044
+Line 1573
      </section>
      <section><title>Attribute Tables</title>
          <para>
-             To clearly separate between both types, Thuban provides
+             To clearly separate between both types of tables (data and
-         functionality regarding the attribute tables under the Layer menu.
+         attribute), Thuban provides functionality regarding the attribute
+         tables under the <menuchoice><guimenu>Layer</guimenu></menuchoice> menu.
          </para>
          <section><title>Show Table</title>
-Line 1097
+Line 1627
      </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>Extensions included in Thuban package</title>
+                 <para>
+                 The extensions described in this section are part of the
+                 Thuban package, but not activated by default.
+                 You will find them in the Thuban installation directory
+                 under <literal>Extensions/</literal>. Activate them as personal
+                 extensions via PYTHONPATH as described in the previous section.
+                 Stable extensions will appear under the menu
+                 <menuchoice><guimenu>Extensions</guimenu></menuchoice> and
+                 extensions which are in experimental state and therefore
+                 not fully functional under
+                 <menuchoice><guimenu>Experimental</guimenu></menuchoice>.
+                 </para>
+                 <section><title>Stable extensions</title>
+                     <para>
+                     These extensions provide extra-functionality to Thuban
+                     that has not (yet) been integrated in the main application.
+                     They are considered to be free of bugs, but may be
+                     further polished with helpful user interactions.
+                     </para>
+                     <section><title>gns2shp</title>
+                                 <para>
+                                 This tool converts data of the Geospatial Names Server
+                                 (GNS, see <ulink url="http://www.nima.mil/gns"/>)
+                                 into Shapefile format.
+                                 The above web-site offer to download named places
+                                 information grouped by countries for all of the world
+                                 except USA for which other data are provided.
+                                 </para>
+                                 <para>
+                                 If you download and unpack a package, you will have
+                                 a text-file with suffix .txt.
+                                 Selecting such a file via gns2shp will create the
+                                 corresponding Shapefile with the same basename and
+                                 place it in the same direcory. Afterwards it
+                                 is automatically loaded into Thuban.
+                                 The Shapefile will not automatically be delete afterwards.
+                                 </para>
+                                 <para>
+                                 The gns2shp.py module can also be executed on the
+                                 command line for batch processing purposes.
+                                 </para>
+                                 <para>
+                                 A sample (<literal>ls.txt</literal> for Liechtenstein)
+                                 is included in the directory
+                                 <literal>Extensions/gns2shp/test</literal>.
+                                 </para>
+                     </section>
+                     <section><title>SVG Export</title>
+                         <para>
+                         Map and legend can be exported separately in the
+                         Thuban-Map-SVG format.
+                         You get files that comply with
+                         the Scalable Vector Graphics (SVG) 1.1 Specification
+                         and can be read by many vector drawing applications.
+                         </para>
+                         <para>
+                         Goal of svgexport is to provide
+                         the start of a printing pipeline for Thuban.
+                         For this purpose the written Thuban-Map-SVG files
+                         contain information that can be used in postprocessing.
+                         Typically a general vector drawing application is
+                         more powerful then a geographic information viewer;
+                         e.g. having much fancier symbols and fonts.
+                         Also users benefit much more when learning to use a
+                         more general application they can also use for other
+                         tasks.  So the charming idea is to enable
+                         the drawing application to postprocess a Thuban maps.
+                         So thee xtra information in the format will make it
+                         possible to export from Thuban and if a few geoobjects
+                         change, and keep the general layout and style
+                         of the full map in the vector drawing appplication.
+                         </para>
+                         <para>
+                         Markus Rechtien has developed a prototype of this
+                         printing pipline as his Diplom thetis, showing
+                         the feasability of Bernhard Reiter's concept.
+                         Scripts exist for the drawing application Skencil
+                         (<ulink url="http://www.skencil.org"/>).
+                         </para>
+                         <para>
+                         Technical notes: the names of the layers are used
+                         as base for ids within the SVG format.
+                         If you try to export with two layers having
+                         the same name, you will get a name clash error.
+                         Just change one of the layer names and try again.
+                         </para>
+                     </section>
+                 </section>
+                 <section><title>Experimental extensions</title>
+                         <para>
+                         All all of these functions have to be handled with care,
+                         since they are neither complete nor well tested.
+                         They are to be seen as a proof-of-concept and may
+                         additionally in some cases of practical help.
+                         </para>
+                         <para>
+                         Any interest on further improvement of these extensions
+                         should be communicated towards the developer and user
+                         community.
+                         </para>
+                         <section><title>importAPR</title>
+                                 <para>
+                                 This command offer to load an ESRI� ArcView� project
+                                 file (suffix .apr) and convert it for use within Thuban.
+                                 After selecting a apr-file to load, a list
+                                 will be presented that offers to select one of the views
+                                 of the apr-file, provided there is more than one.
+                                 Furthermore, the Session Info-Tree is extended with
+                                 a complete representation of the parsed apr-file.
+                                 </para>
+                                 <para>
+                                 The legend of Thuban does not yet cover all of the elements as
+                                 supported by the legend of ArcView�. Therefore, the Thuban
+                                 map will look different. Furthermore, the apr-format is
+                                 a proprietary format, not openly documented.
+                                 Therefore, the interpretation is
+                                 partly based on reverse engeneering and good guessing.
+                                 </para>
+                                 <para>
+                                 The file-paths within the apr-file may not fit and potentially
+                                 are subject to fix in the apr-file. You can do this
+                                 applying any text editor. The paths are either absolute
+                                 or relative from where Thuban has been started.
+                                 </para>
+                                 <para>
+                                 A sample for the Iceland data is included as
+                                 <literal>Extensions/importAPR/samples/iceland.apr</literal>.
+                                 The file-paths are relative from the Thuban main directory.
+                                 </para>
+                         </section>
+                 </section>
+         </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.FindOrInsertMenu('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>
-     <variablelist>
+     <para>
-     <varlistentry>
+     <itemizedlist>
-     <term>After adding two or more layers nothing is being drawn in the
-     map window.
-     </term>
      <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 layer's projections
+     must be set on all layers and on the map itself if the layers' projections
      are different.
      </para>
      </listitem>
-     </varlistentry>
-     <varlistentry>
-     <term>Thuban crashes on startup with the error
-         <literal>NameError: global name 'False' is not defined</literal>.
-     </term>
      <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>
-     </varlistentry>
-     <varlistentry>
+     <listitem>
-     <term>After compiling Thuban, Thuban crashes with an error similar to
+     <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>
-     </term>
+     </para>
-     <listitem>
      <para>
      Thuban depends on the wxWindows library. If Thuban is compiled with an
      incompatible version of the compiler than wxWindows was compiled with
-Line 1141
+Line 2008
      compiler.
      </para>
      </listitem>
-     </varlistentry>
+     </itemizedlist>
-     </variablelist>
+     </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>
-Line 1178
+Line 2062
      </listitem>
      </varlistentry>
+     <varlistentry>
+     <term>PostGIS</term>
+     <listitem>
+         <para>
+         PostGIS adds support for geographic objects to the PostgreSQL
+         object-relational database. Different layer types (as for Shapefiles)
+         are supported. <ulink url="http://postgis.refractions.net">PostGIS
+         Homepage</ulink>
+         </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>Working with PostGIS</title>
+   <para>
+   This section focusses on the use of PostGIS in the Thuban framework. For
+   installation and maintenance of spatial databases we refer to the
+   <ulink url="http://postgis.refractions.net">PostGIS Homepage</ulink>.
+   The Thuban PostGIS support requires the
+   <ulink url="http://initd.org/software/psycopg">psycopg module</ulink>.
+   </para>
+   <para>
+         Working with PostGIS Databases is seperated into two steps:
+         <itemizedlist>
+         <listitem><para>Opening a Database Connection</para></listitem>
+         <listitem><para>Loading a Data Layer</para></listitem>
+         </itemizedlist>
+   </para>
+         <section><title>Opening a Database Connection</title>
+         <para>
+                 Before a data layer can be loaded from a PostGIS database a
+                 connection with the database has to be established.
+                 <menuchoice>
+                 <guimenu>Session</guimenu>
+                 <guimenuitem>Database Connections ...</guimenuitem>
+                 </menuchoice> opens a dialog for database connection
+                 management. In the dialog new connections can be added
+                 and existing ones can be removed. Removing a database
+                 connection is not possible if the map still displays a
+                 layer provided by this database connection.
+         </para>
+     <figure>
+     <title>Database Management Dialog</title>
+     <mediaobject>
+     <imageobject><imagedata fileref="../images/app_postgis_db_management.png" format="PNG" scale="&imgscale;"/></imageobject>
+     <imageobject><imagedata fileref="./images/app_postgis_db_management.eps" format="EPS" scale="&imgscale;"/></imageobject>
+     </mediaobject>
+     </figure>
+         <para>
+                 To add a new database connection to the session a dialog is
+                 opened to specify the relevant connection data. Enter all
+                 data relevant for your connection. If the connection fails
+                 the dialog remains open and provides some hints on the failure.
+         </para>
+         <figure>
+         <title>Add Database Dialog</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/app_postgis_db_add.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/app_postgis_db_add.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         <para>
+         It is important to note that information on database connections are
+         also stored with the session. Passwords are NOT stored. If you load a
+         session with database connections you are asked to enter these
+         passwords again where required.
+         </para>
+         </section>
+         <section><title>Loading a Data Layer</title>
+         <para>
+         Data layers as part of a map are loaded with the
+         <menuchoice>
+         <guimenu>Map</guimenu>
+         <guimenuitem>Add Database Layer ...</guimenuitem>
+         </menuchoice> menu item. A dialog is raised displaying two choice
+         lists. In the left list all connected databases are shown.
+         Highlighting
+         one of these and issuing a retrieval results in a list of available
+         layer tables from that database. After selection of a
+         layer the dialog is closed.
+         </para>
+         <figure>
+         <title>Add Database Dialog</title>
+         <mediaobject>
+         <imageobject><imagedata fileref="../images/app_postgis_add_layer.png" format="PNG" scale="&imgscale;"/></imageobject>
+         <imageobject><imagedata fileref="./images/app_postgis_add_layer.eps" format="EPS" scale="&imgscale;"/></imageobject>
+         </mediaobject>
+         </figure>
+         </section>
+   </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 and are available through the Projections dialog.
+     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></para></listitem>
-     </varlistentry>
-     <varlistentry>
-     <term>Lambert Conic Conformal</term>
-     <listitem><para></para></listitem>
-     </varlistentry>
-     <varlistentry>
-     <term>Transverse Mercator</term>
-     <listitem><para></para></listitem>
-     </varlistentry>
-     <varlistentry>
-     <term>Universal Transverse Mercator</term>
-     <listitem><para></para></listitem>
-     </varlistentry>
-     </variablelist>
    </appendix>
  </book>

 Legend:



Removed from v.1496
 


changed lines


 
Added in v.2670
 Legend:



Removed from v.1496
 


changed lines


 
Added in v.2670
-Removed from v.1496
+Added in v.2670

[email protected]	ViewVC Help
Powered by ViewVC 1.1.26