                               ---------
    RoadMap - a street navigation system using the US Census maps and GPS
                               ---------
                Pascal Martin (pascal.martin@ponts.org)
                               ---------
                             November 2003


INTRODUCTION

   RoadMap is an open source program for UNIX that displays street maps.
   When a GPS receiver is available RoadMap can track the current location
   of the vehicule on the screen, continuously adjusting the position of the
   map; it can also identify the name of the current street as well as the
   name of the next intersection. RoadMap can be used without a GPS receiver,
   as a static map viewer and address finder.

   Most of the maps are provided by the US Census Bureau, which only cover
   the US. RoadMap now includes a preliminary support for the Digital Charts
   of the Words (DCW), a set of world-wide maps produced by the US Department of
   Defense. The DCW contains only major highways and freeways, for some parts
   or the world (mostly Europe and japan) and their accuracy does not allow
   any reliable car navigation.

   RoadMap is released under the GPL (see the COPYING file). The US Census
   Bureau's data is public domain. The DCW data is mostly public domain, but
   some administrative boundary data is copyright of ESRI
   ({{http://www.esri.com/}}). As no administrative data is incorporated in
   the RoadMap map files, all the RoadMap map files are in the public domain.

   RoadMap uses a binary file format for representing the maps that is
   compact enough to allow the storage of many maps on a Compact Flash or
   MultiMedia card. The map of Los Angeles county takes a little more than
   10 Mbytes of flash space. RoadMap comes with a set of tools to convert
   the US Census bureau data into its own map format.

   RoadMap has been designed to be usable on both a desktop or laptop
   computer, or on a PDA such as the iPAQ from HP (formely from COMPAQ)
   or the Sharp Zaurus.
   
   In its current version, RoadMap can work with either the GTK+ 1.2,
   GTK 2.0, GPE, QT/X11 or QT/QPE graphic environments. The QT environment
   --especially its QT/QPE version--is mostly used for the Zaurus port (but
   could probably be used with OPIE). RoadMap is configured for using QT3
   by default, but the QT2 compatibility headers must be installed (the
   QT2-style coding has been kept because of the Zaurus QPE environment).
   The GTK 1.2 environment is being phased out (due to its old age). The
   most stable environment is the GTK 2.0 one (this is the one used for
   developping RoadMap). The GPE support is and optional extension of the
   GTK 2.0 environment and is still very experimental (i.e. untested).

   RoadMap is also available on Windows CE (i.e. Pocket PC). As gpsd does
   not exist on Windows, the Windows version directly listens to the GPS
   serial port.

   RoadMap is at an early stage of development. At this time all the
   features have not been implemented yet. RoadMap can display the map
   around a specified street address, track a GPS position and identify
   the current street and the next intersection. A basic trip support is
   provided (waypoints and destination). RoadMap detects what is the next
   waypoint, provides a direction arrow and show the distance to this
   waypoint (and/or to the destination).

   The plan for the future is to implement some navigation features similar
   to those found in commercial car navigation systems, and to port RoadMap
   to as many environment as possible.


ABOUT THIS DOCUMENTATION

   This documentation was written using vi (what else? :-) in the format
   supported by aptconvert. The aptconvert tool was used to produce the HTML
   version of this manual (file web/manual.html). The HTML file can be
   regenerated using the following command:

----
      aptconvert -toc web/manual.html README
----
   
   The aptconvert tool is available at 
   {{http://www.xmlmind.com/aptconvert.html}}.


INSTALLATION

* DEPENDENCIES

   RoadMap communicates with a GPS receiver using the NMEA 0183 protocol.
   RoadMap has been tested with a Garmin 38. The GPS receiver must be
   configured with the datum set to either NAD83 or WGS 84.

   RoadMap communicates with the GPS receiver through gpsd, a GPS
   communication daemon for UNIX. Therefore gpsd is required for RoadMap
   to take advantage of a GPS receiver. However gpsd is not required when
   building RoadMap, and RoadMap can run without gpsd as a static map viewer
   or address finder. In addition, gpsd may run on a remote computer
   accessible through a TCP/IP network: in this case gpsd must be installed
   on the remote computer, but is not needed on the local computer. A
   typical setup is to have gpsd on the same computer, in which case
   the GPS source should be set as "gpsd://localhost".

   RoadMap uses either GTK, GTK2 or QT for its user interface. One of these
   toolkits must be installed. RoadMap can be built for QT/QPE, but the
   RoadMap makefile for QT must be modified.

   RoadMap uses the ImageMagick package to generate the PNG files for some
   icons of its toolbar. ImageMagick is only required for building RoadMap,
   it is not necessary when running RoadMap.

   RoadMap uses flite (festival lite) to generate voice messages. See
   section "VOICE INTERFACE" for more information.

   RoadMap uses aptconvert to format the documentation (see previous section).

   Support for a "Point of Interest" feature is in the way, where the plan
   is to store the points in a SQLite database. RoadMap is not at this time
   dependent on SQLite, even while using SQLite will be an option in the
   future.

   By default RoadMap use the shapelib library (to decode the shape file
   format). The shape file format is only used for converting the Digital
   Charts of the World. If only US maps from the census bureau are used,
   or if only pre-built maps are used, then there is no need for shapelib:
   build RoadMap with the make option: SHAPEFILES=NO.


* WINDOWS SPECIFIC DEPENDENCIES AND LIMITATIONS

   The port of RoadMap on Windows is recent, not fully complete and has
   not been tested thoroughly, so problems are to be expected. Thank you
   for your understanding.

   The port to Windows was implemented by Ehud Shabtai (eshabtai@gmail.com).

   RoadMap is only available for PocketPC 2002 and later at that time.
   There is no support yet for Windows XP, 2000 or 2003. This is because
   the WIN32 API is not the same on all Windows platforms: to the extend
   of our knowledge, RoadMap might not compile, and should not run, on
   Windows XP.

   RoadMap use the WIN32 API exclusively, and no specific graphic library
   is required.

   Maps cannot be built under Windows (buildmap and buildus have not been
   ported yet). Maps built under Linux can be used on PocketPC systems,
   however.

   The flite software is available under Windows: a PocketPC 2002 (ARM)
   binary is available on the RoadMap project's SourceForge web site. The
   flite.exe binary must be installed in the same folder as the roadmap.exe
   binary.

   The gpsd software is not available on Windows. Note that network access
   to a remote gpsd is possible (the remote computer must run UNIX).

   Instead of a local gpsd, RoadMap can uses a Windows serial port and the
   GPS source should then be specified as "COM1:", "COM2":, etc...
   
   The roadmap and roadgps programs cannot run simultaneously when configured
   for the serial port. The "GPS Console" menu item of roadmap does not work
   in that configuration.

   Only NMEA-capable GPS devices are supported, unless a remote gpsd is used.

   Downloading maps on the fly is not available on Windows, due to the lack
   of gzip and tar tools on PocketPC.

   The screenshots feature of RoadMap is not available on Windows.

   The full-screen mode of RoadMap is not available on Windows.


* {DIRECTORIES}

  RoadMap is to be installed in a few different directories, where each
  directory contains a specific type of file: commands, configuration files,
  icons and maps.

  Before you install RoadMap, you must choose what installation directories
  to use for these files. Some of these choices are already made for you when
  you install a pre-built package (such as the Familiar ipk package), or are
  assigned default values in the make files (source package). This section
  describes the whole thing, regardless of how you install RoadMap. It also
  provides some information about the standard locations in the most common
  cases.

  RoadMap supports lists of directories, instead of a single location, for
  each type of files. That does not mean you must install the RoadMap files
  in every of these directories, only that you can install the files in any
  of these directories.
  
  One reason for RoadMap to support a list of directories is to define a
  default system-wide configuration, and at the same time to allow a specific
  user to install it's own setup. Another reason (for the map files on a PDA)
  is to let the users choose the type of hardware storage that is convenient
  for them.

  The RoadMap commands must be installed in a bin directory. This is an
  easy one: the only requirement is that this directory must appear in the
  PATH variable (either you choose an existing directory or you add your own).

  RoadMap comes with some critical configuration files (files sprites,
  schema, preferences, etc..). RoadMap supports these files to be in a few
  different places, which list cannot be changed in the user preferences
  since it is used to load the preferences themselves.
  
  On most UNIX systems this list is:
  
         * /etc/roadmap,

         * /usr/local/share/roadmap (preferred path),

         * /usr/share/roadmap and

         * ~/.roadmap.
         
  As an exception, the list on the Zaurus is:

         * /opt/QtPalmtop/share/roadmap,

         * /mnt/cf/QtPalmtop/share/roadmap (preferred path),

         * /mnt/card/QtPalmtop/share/roadmap and

         * ~/.roadmap.

  On Windows CE this list is:

         * \Program Files\roadmap

         * \Storage Card\roadmap (preferred path)

  RoadMap (GTK version) needs some icons. These icons must be placed
  in some standard location:
  
         * ~/pixmaps,

         * /usr/local/share/pixmaps or

         * /usr/share/pixmaps.

  RoadMap needs some county maps to serve any useful purpose.
  The location for these map files can be redefined in the user preferences
  (item Map.Path). The maps are a problem of their own, since they may require
  a huge space (up to 1.8 G Bytes for the full set). It is recommended to share
  these maps between users. Because these maps are not architecture-independent
  you should be careful, however, not to share them on a network (this could
  also be very inefficient, both from a network and performances point of
  view).
  
  By default, RoadMap is built to search for these directories on most
  UNIX systems:
  
         * ~/.roadmap/maps,

         * /var/lib/roadmap (preferred path) and

         * /usr/lib/roadmap

  (RoadMap also searches in /usr/local/share/roadmap and /usr/share/roadmap,
  but this is in violation of the FHS filesystem standard, since these maps
  are not architecture-independent).
  
  The Zaurus is a special case again, as the default path on these systems is: 

         * /opt/QtPalmtop/share/roadmap,

         * /mnt/cf/QtPalmtop/share/roadmap (preferred path) and

         * /mnt/card/QtPalmtop/share/roadmap
         
  (Note that the two last directories are located on a memory card, as this
  would be the only reasonable place where to install the maps considering
  their size.)

  The Linux/familiar package is also an exception, for the same reasons
  as the Zaurus (i.e. using memory cards):

         * ~/.roadmap/maps,

         * /usr/share/roadmap,

         * /mnt/hda/share/roadmap and

         * /mnt/card/share/roadmap

  On Windows CE the default map search path is:

         * \Program Files\roadmap\maps

         * \Storage Card\roadmap\maps (preferred path)


* DOWNLOADING

   RoadMap can be downloaded from the RoadMap web site:

         * {{http://roadmap.digitalomaha.net/download.html}}

   RoadMap is distributed with the map of San Francisco as an example of
   map. The complete set of maps is available on the following web site:
   
         * {{http://roadmap.digitalomaha.net/maps.html}}

   The RoadMap directory file (usdir.rdm) must be downloaded first, as
   RoadMap will not work without it.

   Please refrain from downloading all the US states at once, as the map
   files are huges and the bandwidth is expensive. If you do need the
   complete set, please drop an email to the author.
   
   It is recommended to install the maps in one of the default directories
   (see previous section). You may also install the maps in any directory,
   assumed you change Map.Path accordingly in the RoadMap preferences.

   Roadmap comes either as a set of sources, or as a set of binary files,
   depending on which distribution you downloaded. RoadMap comes in three
   distribution formats:

      * a binary tarball with executables for Linux/i686.

      * a set of .ipk packages for Linux/armv4l (Linux/Familiar).

      * a source tarball.

   The arm and i686 executables use the same map files. Please note that
   the map files are dependent on the computer's endianess: map files
   built on a Mac (PowerPC CPU) would not be compatible with an Intel or
   (small endian) ARM computer.

   Note: the main GTK RoadMap executables (roadmap and roadgps) are
   built as "gtkroadmap" and "gtkroadgps", while the QT equivalent are
   built as "qtroadmap" and qtroadgps" to avoid a clash. These executables
   are installed under their "standard" names using symbolic links, so
   that only one version can be installed at a time (the reason is to
   share one roadmap.menu file..).

   A version of RoadMap for the Sharp Zaurus was available at
   {{http://community.zaurus.com/projects/zroadmap/}}


* INSTALLING FROM THE BINARY TARBALL

   The binary distribution contains three sets of files: the directory
   src/gtk contains the executable files for Debian GNU/Linux (kernel 2.4)
   and the directory src contains the example map datafiles.

   RoadMap can be installed as follow (you will likely need to be logged
   as root):
   
   mkdir /usr/share/local/roadmap
   cd roadmap-<version>/src
   cp sprites preferences schema session /usr/share/local/roadmap
   cp roadmap.1 roadgps.1 /usr/local/share/map/man1
	cp roadmap*.png icons/rm_*.png /usr/local/share/pixmap

   You can then choose to install the GTK2 version:

   cp gtk2/gtkroadmap /usr/local/bin/roadmap/roadmap
   cp gtk2/gtkroadgps /usr/local/bin/roadmap/roadgps

   or the QT version (requires QT3):

   cp qt/qtroadmap /usr/local/bin/roadmap/roadmap
   cp qt/qtroadgps /usr/local/bin/roadmap/roadgps

   The "make install" command from one of the graphical toolkit directories
   (gtk2, gtk or qt) will do the job for you (it must be run as root). This
   installs the associated set of RoadMap executables and all configuration
   files (but not the maps!).

   RoadMap will not work without the maps, which can be downloaded from
   the RoadMap web site:

         * {{http://roadmap.digitalomaha.net/maps.html}}

   Please install usdir.rdm first. See the DOWLOADING section for more
   information.


* INSTALLING FROM THE FAMILIAR PACKAGE

   The RoadMap familiar distribution contains one .ipk package file. This
   package contains the RoadMap executables (roadmap and roadgps) as well as
   the configuration files for a GTK 2.0 setup (such as the Familiar 0.7.2 GPE
   image). This package does not contain the map files or the map index file.

   If RoadMap is available from your feed:

----
      ipkg install roadmap
----

   If you downloaded the ipk files on the iPAQ:

----
      ipkg install roadmap_X.Y.Z_arm.ipk
----

   RoadMap is useless without maps. The maps can be downloaded from the
   web site ({{http://roadmap.digitalomaha.net/maps.html}} or mirrors) or
   generated from the US Census Bureau's files (see later).

   It is strongly recommended you install the maps on a CompactFlash or
   SD/MMC card, and not on the iPAQ internal flash. The reason is that the
   maps are way too big to be installed on the iPAQ flash. As configured,
   RoadMap will look for the maps either in
   
           * /mnt/hda/share/roadmap or

           * /mnt/card/share/roadmap.

   (This can be changed using the Map.Path item in the RoadMap preferences
   dialog.)

   The set of maps for California represents more that 100 Mbyte of data,
   the whole US about 1.6 Gbyte. Unless you are the lucky owner of a large
   capacity CompactFlash, you will have to install a subset. A capacity of
   128 Mbyte is enough in most cases, 64 Mbyte might be enough if you do not
   travel far from home.

   To build the maps yourself, you need the Linux/i686 binary or the source
   tarball. See the next section for more details.


* INSTALLING FROM THE SOURCE TARBALL (UNIX)

   It is also possible to rebuild RoadMap and the map files from scratch
   from the source distribution:

   [[1]] Install the development libraries for GTK+ 1.2, GTK+ 2.0 or Qt.

   [[2]] Install the RoadMap's tarball:

----
      tar xzvf <tarball>
----

   [[3]] Compile the map building tools:

----
      cd roadmap-<version>/src
      make build
----

   [[4]] Compile roadmap for the GTK, GTK2 or the QT toolkit:

----
      make DESKTOP=GTK    -- if using the GTK 1.2 toolkit

      make DESKTOP=GTK2   -- if using the GTK 2.0 toolkit

      make DESKTOP=GPE    -- if using GPE with the GTK 2.0 toolkit

      make DESKTOP=QT     -- if using the QT toolkit

      make DESKTOP=QPE    -- if using the QT/QPE toolkit
----

      If you want to build all three versions of RoadMap (GTK, GTK2
      and QT), just type:

----
      make       -- This replaces steps 3 and 4.
----

      <<Note for QT users>>: the RoadMap QT module is built with QT3 by
      default, but requires the QT2 compatibility headers.

      <<Note for developpers>>: using the option MODE=DEBUG causes RoadMap
      to be compiled in debug mode.

   [[5]] download some maps from the US Census bureau:

         {{http://www.census.gov/geo/www/tiger/tiger2004se/tgr2004se.html}}

   This download can be automated by using the shell script
   roadmap/src/rdmdownload:

----
      rdmdownload <tiger-path> [<state-symbol> ..]
----

   <<CAUTION>>: the command above downloads the tiger 2002 files. to download
   the tiger 2000 files, use the <<format>> option:

----
      rdmdownload <tiger-path> format=2000 [<state-symbol> ..]
----

   [[6]] download the list of counties from the US Census bureau:

         {{http://www.census.gov/geo/tigerline/app_a02.txt}}

      (A world-extended version of app_a02.txt is provided in directory src.)

   [[7]] Build the maps:

----
      rdmgenmaps <tiger-path> maps=<map-path>
----

   This command processes all the Census Bureau files found in <tiger-path>
   and creates the map files for RoadMap in the <map-path> directory. There
   is one map file generated for each county.

----
      rdmgenmaps <tiger-path> [maps=<map-path>] <county> ..
----

   This other command processes only the listed counties. The county
   shall be identified by its FIPS (e.g. 06075 for San francisco, CA).

   <<CAUTION>>: the description above assumes the tiger 2002 format. use
   the option <<format=2000>> to convert tiger 2000 files. For example:

----
      rdmgenmaps <tiger-path> format=2000 [maps=<map-path>]
----

   The rdmgenmaps command can also process one full state at a time:

----
      rdmgenmaps <tiger-path> maps=<map-path> state=<state-id>
----

   where the state-id is the two first digit of the FIPS (such as 06 for
   california).

   The rdmgemaps tool is a shell script that extract the TIGER files from
   the downloaded ZIP files, invokes the buildmap tool and then cleans
   up the TIGER files. Last, rdmgemaps invokes the buildus tool to generate
   the US states & counties catalog. The main purpose of rdmgenmaps is really
   to keep the TIGER files in compressed form, considering their huge size..


   The <<buildmap>> tool takes a county "FIPS" and a TIGER file as input and
   produces one RoadMap .rdm map file. The tool uses the popt library for
   parsing the command line arguments: the option --help gives more
   information about the available options.

   Here is an example:

----
      buildmap 01001 /tmp/TGR01001.RT1
----

   The <<buildus>> tool creates a catalog of maps that is used by RoadMap
   to combine all states & counties into a giant US map. It looks for:

      [[a]] the file AllSt.txt and

      [[b]] the various existing RoadmMap maps.

   This is not a problem if the catalog references a map file that does not
   exists: this way it is possible to store locally only a small portion of
   the US maps. This is useful when using a PDA with limited storage space
   (like the iPAQ).

   The buildus tool also uses popt for parsing the command line arguments:
   the option --help gives more information about the available options.

   [[8]] run make to install roadmap:

------
      cd gtk        -- or gtk2 or qt, depending on your preferences.
      make install
      cd ..
------

   This last step installs the RoadMap executables. These executables
   and the maps should have been generated at their proper location in
   steps 3 to 8. The install is not required for running RoadMap: the
   programs and build tools) can run from the local directory as well.


* INSTALLING FROM THE SOURCE TARBALL (WINDOWS CE)

   RoadMap can be built from sources for Windows CE on a Windows XP or
   2000 computer. The Embedded Visual C++ tool version 3 or 4 is required.
   These tools can be downloaded for free from the Microsoft web site, see:
   
           {{http://msdn.microsoft.com/embedded}}

   Note that not all RoadMap programs can be built on Windows. More
   specifically, the tools used to build the maps are available only on UNIX.
   However the maps available from the RoadMap web site do work with the
   Windows version of RoadMap.

   The directory src/win32/wince_env contains a workspace file (Roadmap.vcw)
   that must be used to build roadmap and roadgps.


* A NOTE ABOUT THE ROADMAP ICONS

   The RoadMap toolbar uses road signs as icons. These icons come with
   the application (in directory src/icons). The icon source set is made
   of a mix of PNG and XPM files. The final icon files must all be PNG.

   A make script builds all the necessary files using the ImageMagick
   package. The icon files are built (or installed) when building (or
   installing) RoadMap.

   The PNG icon files must be installed in one of the following directories
   (the order below reflects the search order):

------
      ~/pixmaps
      /usr/local/share/pixmaps
      /usr/share/pixmaps
------


* TROUBLESHOOTING THE INSTALLATION

   This section describes the most common problems encountered when installing
   RoadMap:

   * When running "make build"  a compiler error message appears, complaining
     that the file shapefil.h cannot be found. This is typically happening if
     the shapelib library was not installed. The shapelib library is only
     used to create additional maps using the Digital Charts of the World.
     If only the US maps are required, or if the pre-built maps will be used,
     it is possible to build RoadMap without the shapelib, using the option
     "-SHAPEFILES=NO" in the make command.

   * The display shows no street; lakes, parks, airport and hospitals
     appear as block areas. This is typical of a missing "schema" file.
     The "schema" file must be located in one of these directories:
     /urs/local/share/roadmap, /usr/share/roadmap or /etc/roadmap.
     It is likely the "make install" step was not performed.

   * The display is all black. RoadMap seems to find the map files and
     one can select streets on the screen, but it seems everything is
     drawn black on black. It appears that some old versions of the
     "schema" file can cause this problem. The old file might be located
     in ~/.roadmap, so that it preempts the normal (up-to-date) file.
     This may also happen on a QPE-based PDA: this may be a problem with
     QPE not defining color names. Try redefining all colors in schema
     using the RGB syntax ('#' followed by an hexadecimal RGB value).

   * Waypoints, the compass and the vehicule's location all appear as small
     black squares. This is typical of a missing "sprites" file. The "sprite"
     file must be located in one of these directories:/urs/local/share/roadmap,
     /usr/share/roadmap or /etc/roadmap.  It is likely the "make install"
     step was not performed.


ROADMAP APPLICATIONS

   RoadMap includes the following applications:

   [roadmap]         This is the main application. It displays the map
                     and can keep track of the current GPS position.
                     Depending on which toolkit you use, this will be
                     roadmap/src/gtk/gtkroadmap, roadmap/gtk2/gtkroadmap
                     or roadmap/src/qt/qtroadmap (zroadmap on the Zaurus).

   [roadgps]         A very handy GPS console, inspired by the Garmin
                     satellite status page, with a NMEA log capability.
                     Thanks to gpsd, roadgps and roadmap can be active
                     at the same time. Depending on which toolkit you use,
                     this will be named roadmap/src/gtk/gtkroadgps,
                     roadmap/gtk2/gtkroadgps or roadmap/src/qt/qtroadgps
                     (zroadgps on the Zaurus).

   [buildmap]        A program that takes the US Census Bureau files
                     as input and produces the map files used by roadmap.
                     This application is to be run once on a desktop or
                     beefed-up laptop to prepare the map files and is not
                     needed when using roadmap.

   [buildus]         A program that takes a set of roadmap map files and
                     produce a directory file that helps roadmap choose
                     the map(s) to display according to the location or
                     city. This application is to be run once on a desktop
                     or laptop and is not needed when using roadmap.

   [dumpmap]         Display the data tables from a map file. This application
                     is used for debug purposes only and is not needed when
                     using roadmap.

   [rdmgenmaps]      A script to simplify the generation of the maps.


USING ROADMAP

* COMMAND LINE {OPTIONS}
   
   The options marked as "sticky" remain in effect the next time RoadMap
   is run. The use of the option actually changes the specified RoadMap
   preferences item.

   The RoadMap application accepts the following command line options:
   
   [--location=<LONGITUDE,LATITUDE>] Set the location point (see menu entry
       View/Show Location..). This option is sticky (preference item
       Locations.Location=<LONGITUDE,LATITUDE>).

   [--metric] Use the metric system for all units. This option is sticky
      (preference item General.Unit = "metric").

   [--imperial] Use the imperial system for all units. This option is sticky
      (preference item General.Unit = "imperial").

   [--no-area] Do not show the polygons (parks, hospitals, malls, airports,
      etc..).

   [-geometry=<WIDTHxHEIGHT>] See option --geometry=<WIDTHxHEIGHT>.

   [--geometry=<WIDTHxHEIGHT>] Sets the geometry for the RoadMap main window.

   [--geometry:<WINDOW>=<WIDTHxHEIGHT>] Set the geometry of a specific RoadMap
      window, according to its title. --geometry:Main=<WIDTHxHEIGHT> is
      equivalent to --geometry=<WIDTHxHEIGHT>. If the window's title includes
      any space, dashes can be used in place of the spaces (the goal here is
      to be shell friendly). This option is sticky (preference item
      Geometry.<WINDOW> = <WIDTHxHEIGHT>).

   [--no-toolbar] Do not show the toolbar. This option is sticky (preference
      item General.Toolbar = "no").

   [--no-icon] Do not show any icon, i.e. keep as much space as possible
      for the map. This option is sticky (preference item General.Icons = "no").

   [--square] Show squares boundaries as grey boxes. This option is for
       debug purpose only.

   [--gps=<URL>] Use a specific GPS source. This option is not sticky: it
       overrides the preferences setting this time, but the preferences
       setting is not modified. The main use of this option is to rerun GPS
       logs created using roadgps.

   [--debug] Print all informational and debug traces.

   [--verbose] Print all informational traces.

   [--help] Show a description of all command line options, key bindings
      and actions (see the section CONFIGURING THE TOOLBAR).

   [--help=SECTION] Show a description of either the command line options
      (--help=options), the key bindings (--help=keymap) or the actions
      (--help=actions).


* GETTING HELP

   The main RoadMap window includes a "Help" menu. This help can be used to
   display various topics from this document. The help text is actually an
   HTML version of this file, shown using a web brower. The default browser
   is "dillo", but this default can be changed in the user's preferences
   (see section PREFERENCE ITEMS).


* THE ROADMAP DISPLAY

   The main RoadMap window shows the menu, the toolbar and the map's canvas.
   The toolbar is optional: all the commands are also available from the menu
   bar or from the keyboard or iPAQ buttons.

   When RoadMap starts, the map view reflects the previous session's mode
   If no session data is found, RoadMap tracks the current GPS position. It
   is possible to select another mode: show the current destination point
   (see the section "Managing Trips" below), show a specific location, track
   the GPS position with the north shown up, track the GPS position with the
   direction of movement shown up.

   When RoadMap is in GPS tracking mode, the map view will reflect the
   movement of the car so that the GPS sprite will remains at the predefined
   position (usually the center, but it is possible to move the position of
   the GPS sprite using the arrow keys). The map can be held to its current
   position: the "hold" button freezes the map view to its current location,
   but updates will continue, so that, for example, one should see the GPS
   sprite move away from the map's center. The hold mode make it easy to
   select streets and read street names while on the road. To come back to
   the original map view, this view must be re-selected (for example by
   using the menu command Find / GPS position or the "G" toolbar button).

   RoadMap indicates the current street a few seconds after the GPS position
   reached the street. This display is also shown for a limited time. There
   are several criteria used by RoadMap to "lock" on a street: the distance
   to the street (the closest the better, not more than the value set with
   Accuracy.Street), the direction of the street compare to the direction of
   the vehicule or if the street is connected to the current "locked" street.
   RoadMap uses fuzzy logic to combine these criteria into one single value.
   None of the fuzzyfied values for the distance and direction may be below
   the value set by Accuracy.Confidence, or else the street is not selected.
   The final fuzzy value must also be above the same limit. RoadMap then
   selects the street with the highest fuzzy value.

   RoadMap can also display 3 messages at the following corners of the map:
   bottom left, bottom right and top right (the top left corner is already
   used to show the orientation of the map). These messages can be defined
   by the user using RoadMap's specific format strings (see section
   "Configuring the RoadMap text and voice messages").


* USING THE {MOUSE} OR PEN

   RoadMap use only one mouse button (the left button on a 3 buttons mouse).
   This is because RoadMap is designed for a PDA, where pens are used.

   A short mouse Click or pen tap on the map screen displays the name of the
   closest street (with the selected street block's range of address), road
   or freeway (if any). This display is shown for a limited amount of time
   (see preference "Highlight.Duration").

   A long mouse click or pen tap is reserved for future use (popup menu).

   Dragging the mouse with the button down, or dragging the pen on the
   screen, moves the map display according to the movements of the mouse
   or pen.

   Dragging a map display is a CPU-intensive action, so a few "Style"
   preference items can be used to limit the amount of drawing to be
   performed while doing it.


* {VOICE} INTERFACE

   If the flite program has been installed, or if RoadMap was configured
   for an available speech application, RoadMap will complement the screen
   information with an audio one: Roadmap will "tell" the name of the street
   on the audio output device. As a general rule, RoadMap tries not to repeat
   the same message again, as frequent audio messages tend to border on the
   irritating side. Thus if the same street is selected more than once, the
   screen information will be displayed each time, but the voice messge
   will be provided only once. As voice messages tend to take a significant
   time to be produced, RoadMap memorizes the latest message requested while
   the current message was produced and will 'air" it after the current
   message has been completed. Only one message is stored that way, the last
   requested one: any message generated in between is ignored.

   It is possible to mute the RoadMap's voice, using the File / Mute Voice
   item from the menu bar. The voice can be enabled later using the File /
   Enable Voice item.

   Please note that it is possible to rebuild flite with a better voice than
   the default one. The flite source is available at the CMU web site:

                   {{http://www.speech.cs.cmu.edu/flite/}}

   The flite README file describes how to regenerate flite using another
   voice. Here is an example, courtesy of Scot Wilcoxon:

----
     cd flite
     make clean    # to remove old executable files
     ./configure --with-vox=cmu_us_kal16
     make
----


* {KEY} BINDINGS

   Most of the RoadMap commands are available from the keyboard (so to answer
   requests from my loyal Zaurus fans :). In fact, the button and key bindings
   are common to all ports, but some buttons might not exist on some platforms.

   Please note that all the button and key bindings are case insensitive, i.e.
   the same binding applies to 'A' and 'a' (as well as to "Button-Left" and
   "button-left"--whatever it means).

   On a desktop or laptop (or on the Zaurus), the keyboard keys are mapped
   as follow:

*-----------------+-----------------------------------------------------+
 <<Button-Left>>  |     Move the map view to the left.
*-----------------*-----------------------------------------------------*
 <<Button-Right>> |     Move the map view to the right.
*-----------------*-----------------------------------------------------*
 <<Button-Up>>    |     Move the map view up.
*-----------------*-----------------------------------------------------*
 <<Button-Down>>  |     Move the map view down.
*-----------------*-----------------------------------------------------*
   +              |     Zoom in: enlarge the central part of the map.
*-----------------*-----------------------------------------------------*
   -              |     Zoom out: show a larger area.
*-----------------*-----------------------------------------------------*
   A              |     Show a specified address.
*-----------------*-----------------------------------------------------*
   B              |     Start the trip back to the departure point.
*-----------------*-----------------------------------------------------*
   D              |     Show the destination point.
*-----------------*-----------------------------------------------------*
   E              |     Erase maps among those currently visible.
*-----------------*-----------------------------------------------------*
   F              |     Toggle the full screen mode.
*-----------------*-----------------------------------------------------*
   G              |     Show the GPS position.
*-----------------*-----------------------------------------------------*
   H              |     Hold the map view in its current position.
*-----------------*-----------------------------------------------------*
   I              |     Show a specified street intersection.
*-----------------*-----------------------------------------------------*
   J              |     Rotate the map counterclockwise.
*-----------------*-----------------------------------------------------*
   K              |     Rotate the map clockwise.
*-----------------*-----------------------------------------------------*
   L              |     Show the last selected location.
*-----------------*-----------------------------------------------------*
   M              |     Enable/Disable map download.
*-----------------*-----------------------------------------------------*
   N              |     Create a new trip.
*-----------------*-----------------------------------------------------*
   O              |     Open an existing trip.
*-----------------*-----------------------------------------------------*
   P              |     Stop tracking the current trip.
*-----------------*-----------------------------------------------------*
   Q              |     Quit RoadMap.
*-----------------*-----------------------------------------------------*
   R              |     Set the map back to the default zoom level.
*-----------------*-----------------------------------------------------*
   S              |     Start tracking the current trip.
*-----------------*-----------------------------------------------------*
   U              |     Center the map on the GPS position (north up).
*-----------------*-----------------------------------------------------*
   W              |     Set the selected street block as waypoint.
*-----------------*-----------------------------------------------------*
   X              |     Find an intersection.
*-----------------*-----------------------------------------------------*
   Y              |     Save a screenshot of the current map display.
*-----------------*-----------------------------------------------------*

   The current bindings that are used by the application are printed after
   the options help information when the --help option is used.

   Note for Familiar 0.7.1 GPE users: the GPE environment has defined the
   buttons bindings In a way that makes it impossible for RoadMap to use
   them (the button are mapped to the GPE applications). In this environment
   it is recommended to enable the toolbar to replace the buttons. the joypad
   is still available.


* ON-THE-FLY MAP DOWNLOAD

   Today's PDA have a limited storage space, which must be shared with MP3
   and other files. As the RoadMap maps can take up to 1.6 GB, most PDA users
   will want to install only the few maps they need. The on-the-fly download
   feature of RoadMap helps the user to select visually which maps to download
   or remove. RoadMap is capable of downloading compressed maps: gzip, bzip2
   or lzop compressed files are automatically recognized and uncompressed
   after transfer.

   The map download is available in a special RoadMap mode, which can be
   activated and deactivated using the Find / Map Download menu entry. On
   startup the download mode is always deactivated. RoadMap shows a red
   "download" icone on the right top corner of the map screen to indicate
   that the download mode has been activated.

   In the download mode, if a map is not found by the display engine, the
   user will be asked for the permission to download the file from the
   configured source (as defined in the preference item "Download.Source").
   The destination directory can also be configured (using the preferences
   item "Download.Destination"). Both the source and the destination file
   name can be edited manually before each download.

   RoadMap is designed to support multiple download protocols. The protocol
   is selected depending on the source string, as much as possible using
   the well-known URL syntax. Two protocols are available: a local file
   copy (the source is either a full path or a "file://*" URL) and the HTTP
   protocol (the source is a "http://*" URL). The local file copy protocol
   can be useful in some cases, for example when mounting the map server's
   disk using nfs or smbfs.

   If the suffix of the downloaded file matches a well-known compressed files
   suffix, RoadMap will invoke the appropriate tool to uncompress the file.
   The compression tools supported are gzip (.gz suffix), bzip2 (.bz2 suffix)
   and lzop (.lzo suffix). This feature makes it possible to store compressed
   maps on the server side. Using compressed files may reduce by a factor of
   two the time it takes to download the map, depending on the compression
   tool used, the specific map's content, etc.. Note that maps are always
   stored uncompressed: because RoadMap maps the file in memory, compressed
   file cannot be used by RoadMap.

   If the user cancels the download of a specific map, RoadMap will not
   request the same download again for the remainder of the session. This
   means that RoadMap will request the same maps again if stopped and then
   restarted. This was done because there is at this time no way for the
   user to change his mind and re-request the download of a cancelled map.
   This is a part of the user interface that is likely to change in the
   future.

   RoadMap also provides a dialog for deleting maps, activated through the
   Find / Delete Maps.. menu entry. The dialog shows the number of map files
   stored locally, the total size of the local maps and the list of maps
   currently visible on the RoadMap screen. The proper way for selecting
   maps to delete is to view an area you do not need anymore, hit the Find /
   Delete Maps.. entry, then select a specific county and hit the Delete
   button. The county will immediately disappear from the map screen and
   the dialog gets updated (i.e. the map statistics and the map list will
   reflect the latest delete action). Several counties can be deleted this
   way before the dialog is closed (button "Done").

   Note that a deleted map is automatically added to the "cancel download"
   list, so that RoadMap will not request for this map again. As such, it
   is not a problem to delete maps while the download mode is active. If
   you need to download again a map that was deleted, just restart RoadMap.

   A typical use of the download feature is to preload the maps you need
   before you go on a trip. Activate the download mode and select the
   destination address: RoadMap will request the download on the map that
   covers this destination. Zoom out the display to force the download of
   adjacent counties, if required. Repeat for each place you are likely to
   go to. Use the arrow keys or buttons to "fly over" the roads you are
   going to travel on. If you missed a map, and you did set a public map web
   server, it should be possible to download maps from an hotel's Internet
   access. Of course, if you are (rich and) lucky enough to have an Internet
   connection while on the road, the download feature can also be used at
   any time.

   Here is a typical setup using the HTTP protocol:

     1- Install the individual map files, gzip-compressed, in a "maps"
        subdirectory of the web server directory tree. Say the web
        server is named "desktop".

     2- Set the preference Download.Source to
        {{http://desktop/maps/usc%05d.rdm.gz}}

     3- Set the preference Download.Destination to /var/lib/roadmap

     4- Make sure the preference Map.Path does include the directory
        /var/lib/roadmap.


* WAYPOINTS AND ADDRESSES

   RoadMap manages four types of points: a location point (selected using
   a street address or the mouse), the GPS position (updated automatically
   if a GPS fix is available), a destination point, and an arbitrary number
   of user-defined waypoints.

   One can select which one of these locations serves as the center of
   the map. The GPS and waypoints positions are special cases: see the
   section on trip management.

   The location point is really a buffer for the selection of a street
   block. Once selected, the point can be defined as a (new) waypoint or
   as the destination. Thus the definition of a destination or waypoint
   is a two step procedure: (1) select a location, and (2) set the selected
   point as a waypoint or the destination point (in the Trip menu).

   The location point can be entered in one of three ways:
   - by clicking on a location on the map,
   - by entering a valid USPS address (street number, name, city and state
     names) in the dialog launched by the "View / Show Location.." menu entry,
   - by specifying the intersection of two streets in the dialog launched
     by the "View / Show intersection.." menu entry.

   More details are provided in the following sections.


* {STREET} NAME OPTIONS

   Street names are used in the two dialogs used to select a specific location:
   the address and intersection dialogs. These dialogs follow the same rules
   regarding the format of the names.

   When entering a street name, the street prefix, suffix and type, if provided,
   must be among the abbreviations listed by the US Census Bureau (N for north,
   E for east, Blvd for boulevard, etc..). In almost all cases, the US Census
   Bureau conventions follow the usual abbreviations, so there is no need to
   worry here. In addition, any of these fields is optional: not providing
   them only makes the search less selective. If several matches are found,
   RoadMap shows a list of all matching streets and lets the user select the
   appropriate one.

   The exact format of the data expected by RoadMap as a complete street name
   is as follow:

----
         [prefix ' '] name [[' ' suffix] ' ' type]
----

   The name itself may include space characters. Potential conflicts are
   resolved by excluding the prefix, suffix and type fields from the name
   only when a match is found with the valid set for that county. As such,
   the following names would work OK in any circumstances:

----
         N Rio del Sol St   --> RoadMap detects both a prefix and a type.
         Rio del Sol St     --> RoadMap detects the type, no valid prefix.
         N Rio del Sol      --> RoadMap detects the prefix, no valid type.
         Rio del Sol        --> RoadMap detects no valid prefix or type.
----

   Lets go through an example: we will search for 100 East Washington
   Boulevard in Los Angeles, California. The name of the street should be
   typed as follow:

----
         e washington blvd
----

   The 'e' stands for "east", 'blvd' stands for boulevard, according to the
   US Census Bureau documentation. Note that RoadMap is not case sensitive.

   The result is a single match, so RoadMap shows the location immediately
   without any additional question. However it is possible to omit either
   the prefix, street type, or both, with the effect of broadening the search.
   Let say we entered:

----
         washington blvd
----

   Now RoadMap display a dialog that lists 3 matches:

----
         Washington Blvd, Los Angeles
         W Washington Blvd, Los Angeles
         E Washington Blvd, Los Angeles
----

   The first item in the list is shown selected, and RoadMap displays a new
   location in the map display. In fact, each time the user selects one
   address in the list, RoadMap displays the corresponding map location.
   When the user hits the OK button, this simply confirms the current choice
   as the final one.

   Note that not providing a prefix, suffix or street type does broaden
   the search, but the street name must always be provided in full: at that
   time RoadMap provides only an exact street names search. Thus providing
   "wash" instead of "washington" only triggers the error message "No street
   with that name could be found".


* OTHER ADDRESS OPTIONS

   It is possible not to specify the street number part of an address:
   in that case, all street blocks matching the street and city names will
   be listed. Be careful, that might make a long list, and RoadMap has a
   limit of 256 items per list (matching items beyond the 256th one are
   discarded).

   It is also possible to specify an approximate city search: if the city
   name is prefixed with a character '?', then the name of the city is used
   to find the county, but is not used in the street match: the idea is to
   list all similar addresses around (i.e. in the county). This is useful
   when one is not sure of the city name, or only knows the name of a city
   nearby.


* SELECTING AN INTERSECTION

   The "Find / Intersection.." menu entry activates a dialog that asks for
   two street names and a state name. RoadMap will search within the given
   state for all intersections between streets that match the street names
   provided. This search may take a few seconds, especially if the maps must
   be read from disk.

   In the (likely) case where multiple intersections have been found, RoadMap
   displays a list that shows the name of the city and the name of the county
   where each intersection is located. This selection list follows the same
   rules as the address selection list described in the previous sections.


* SELECTING A POSITION

   The "Find / Position.." menu entry activates a dialog that asks for a
   longitude / latitude position. The format for the longitude and latitude
   must conform to the ISO 6709-1983 standard (with some extensions).
 
   The format for longitude is:

----
   [+-EW][d]dd[mm[ss]][.ffffff][EW]
----
   
   The format for latitude is:

----
   [+-NS]dd[mm[ss]][.ffffff][NS]
----

   Where "[d]dd" or "dd" stands for the degrees, "mm" stands for the minutes,
   "ss" stands for the seconds and "ffffff" stands for the fractional part
   (either fraction of degrees, minutes or seconds, depending on the context).

   The main extensions compare to ISO 6709 are as follow:
   
   * the letters 'E', 'W', 'N' and 'S' are recognized as a replacement
     for '+' or '-', either as prefix or suffix.

   * the longitude may be expressed with 2 digits for the degrees.


* MANAGING {TRIPS}
   
   A trip is made of one destination point and many user-defined waypoints.
   The purpose of a RoadMap trip is to describe a real-life trip and to
   provide the user information about the trip progress.
   
   RoadMap supports an infinite number of trips: each trip context is saved
   in a trip file. One trip at a time can be edited or activated. A saved
   trip can be reloaded from the trip file, of course. each trip support an
   infinite number of waypoints.

   The last trip created or loaded will be reloaded the next time RoadMap
   starts.
   
   A trip must have been loaded before it can be edited. There are three trip
   edition actions available in the "Trips" menu: set the destination point,
   add a waypoint or remove a waypoint. The destination point is defined
   using a street address by selecting the "Set Destination.." entry. A
   waypoint is added by highlighting a location on the map and then selecting
   the "Add as Waypoint" entry. Waypoints can be deleted by selecting the
   "Delete Waypoints.." entry, then selecting a specific waypoint and hitting
   the "Delete" button.

   A trip that has been created or loaded can then be activated. Activating
   a trip defines the departure point (the current GPS location) and
   enable the "trip display" mode, i.e. some trip information displayed on
   top of the map. These trip displays include an arrow beside the GPS
   location symbol to indicate the direction of the next waypoint (if any)
   or else of the destination, as well as user configurable messages, such
   as distance information, at the corners of the map. (see CONFIGURATION
   for more information about these user configurable messages).

   When a trip is active, RoadMap tracks the GPS position in realtime and
   updates its map accordingly. The GPS position can be shown in two modes:
   either North up or GPS direction up depending on the "Display.Rotate"
   preference item. In the second case, the map is rotated according to
   the direction information received from the GPS. This dynamic rotation
   is in addition to the map manual rotation.

   A trip can be stopped at any time and then resumed. Resuming a trip
   does not modify the departure point. The trip can also be resumed in
   reverse mode: in that case the departure point and the destination
   point switch roles. Note that this does not modify the trip, only the
   way RoadMap uses the trip information. The reverse mode makes it
   possible to use the same RoadMap trip on the way back.

   When starting a trip, the map can rotate to match the orientation
   of the vehicule. This display mode is the most convenient as it matches
   the driver's or passenger's view. It is however possible to switch the
   display in the "North Up" mode by changing the preference item
   "Display.Rotate" to "no".


* DRIVERS

   RoadMap can interface with the outside world through separate driver
   applications. A driver can:

         * Receive the current GPS position from RoadMap.

         * Access the RoadMap preferences database.

         * Provide RoadMap with objects to track and update each
           object's position, speed and steering (otherwise called
           "position").

         * Communicate with another application to export RoadMap's
           position or import the position of objects as reported by
           the other application.

   The objects reported to RoadMap have the following attributes:

         * An unique ID used to identify the object within RoadMap.

         * A name used for (future) display.

         * The name of a sprite used to represent the object on the screen.

         * A position, speed and steering.

   All drivers must be listed in the text file ~/.roadmap/drivers. This
   file contains one line per driver, with the following syntax:

----
       <name> : <command>
----

   The command may have any number of parameters (or none). The program must
   be specially designed to interact with RoadMap: do not just use any
   program as a RoadMap driver.

   Once a driver has been declared in the drivers file, it can be enabled
   or disabled by changing the Drivers.<driver> preference item. By default,
   all newly declared drivers are disabled. A disabled driver is known to
   RoadMap, but is not started. Multiple drivers can be enabled at the same
   time, however some drivers may not be designed to be started more than once.

   RoadMap comes with 3 drivers:

         * rdmghost is the driver test program. It is a silly small
           application that echoes back a previous position of RoadMap.
           It shows a green ghost vehicule that seems to chase the
           RoadMap position. The rdmghost driver uses the Ghost.Delay
           preferences items, which sets the delay for echoing the RoadMap
           location (each delay unit generally match one second time).

         * rdmfriends is the driver for the gpsdrive's friends protocol.
           It can connect to a friends server (gpsdrive 2.0.9), advertise
           the RoadMap location and provide RoadMap with the list and
           location of all vehicules known to the friends server. The
           rdmfriends driver use the Friends.Name and Friend.Server
           preferences items. The first item provides the name that
           rdmfriends must use to identify itself to the friends server.
           The second item provides the network address of the friends
           server.

         * rdmkismet is the driver for the kismet wireless network scanner.
           This driver connects to the kismet application and provide
           RoadMap with the list and position of access points kismet is
           detecting (the speed represent the signal strength and the
           steering represents the channel). The rdmkismet driver uses
           the Kismet.Server preferences items that specifies the network
           address of the kismet application.

   These three drivers were designed so each can be started more than once:
   the option --driver=<name> replaces the default driver's name (repectively
   Ghost, Friends and Kismet) with the specified name. This changes the
   category of the driver's preferences items as well. It is thus possible
   for RoadMap to interact with multiple friends servers or kismet scanners.

   For example, the following drivers file declares 2 ghost drivers:

----
      Ghost1: rdmghost --driver=Ghost1
      Ghost2: rdmghost --driver=Ghost2
----


* ROADMAP PREFERENCES

   It is possible to edit the roadmap's preferences (select File/Preferences
   from the menu bar). Most preference items take effect only when roadmap
   start, so quitting roadmap is usually required. Editing the roadmap
   preferences requires a keyboard to be available. One way to configure
   the iPAQ preferences is to run roadmap from the iPAQ, redirected to the
   desktop's or laptop's X server.


USING ROADGPS

   The RoadGps tool can be started on its own (using command line options
   similar to those of RoadMap), or from the RoadMap's File / GPS Console
   menu item.

   The screen shows the list of satellites, their position in the sky
   (north up) and the strength of the signal. It marks in reverse video
   those satellites used to compute the current position.

   More importantly, RoadGps allows to log all the NMEA sentences received.
   RoadGps rotates through up to 127 log files. The log file are created
   in /var/tmp, with the name formatted as: "roadgps-%d.log" (where %d
   represents an integer in the range 1..127).

   This log file can be replayed in RoadMap using the --gps option with
   an absolute file name as an argument. For example:

----
       roadmap --gps=/var/tmp/roadgps-1.log
----

   When RoadGps starts, the logging function is off. Whenever the logging
   function is turned on a new log file is created (if the logging function
   was already on, the current log file is closed and a new one is created).

   RoadGps uses a subset of the RoadMap preferences setup, but has no
   preferences editor of its own: configure RoadMap first, and then use
   RoadGps.


CONFIGURATION

* FILES
   
   The RoadMap configuration is stored in text files located in the following
   directories:

----
            /usr/share/roadmap
            /usr/local/share/roadmap
            /etc/roadmap
            ~/.roadmap (equivalent to "&" in RoadMap)
            ~/.roadmap/trips (equivalent to "&/trips" in RoadMap)
            ~/.roadmap/maps (equivalent to "&/maps" in RoadMap)
----

   The first four directories are searched sequentially: any configuration
   item found in one directory overrides all the same items found in the
   directories listed before. In other words, the configuration is loaded in
   the following order:

      1- /usr/share/roadmap (installation defaults)

      2- /usr/local/share/roadmap (local site defaults)

      3- /etc/roadmap (local machine defaults)

      4- ~/.roadmap (current user configuration)

   The directory <<~/.roadmap>> contains the user configuration: any user change
   to the configuration is written there. The items in the user configuration
   take precedence over the "default" configuration in the "shared" directories.

   The directory <<~/.roadmap/trips>> is used as the default location for the
   trip files. Note that trip files can be stored anywhere, not only in
   <<~/.roadmap/trips>>.

   The directory <<~/.roadmap/maps>> contains map files specific for this user.
   As a general rule, it is not recommended for each user to have their
   own copy of the maps, as these maps take a lot of space. This directory
   can be used however when maps are downloaded on the fly, as shared maps
   are usually not writable for users. The local rules can be established so
   that either all users download maps into the shared repository, or else
   each user manages his own maps. On a PDA or on a personal desktop systems
   the first solution makes the more sense, but for public access computers
   (such as computers at an University) the second solution might be the most
   convenient.

   The user configuration directories are created when needed, if they do
   not exist.

   The syntax of most RoadMap configuration files is similar to the X
   ressources file format (the exceptions are the sprites file and the
   trip files). Each configuration item is represented by one line of text,
   using the following format:

----
            name ': ' value
----

   The following configuration files are used:

     [schema]          The definition of the geographic entities.

     [preferences]     User's preferences.

     [session]         The latest context used (locations)

     [sprites]         The definition of the graphic symbols

     [roadmap.toolbar] (Optional) The actions shown on the RoadMap toolbar.

     [roadgps.toolbar] (Optional) The actions shown on the RoadGps toolbar.

   The session file contains the state of roadmap, which is saved (if needed)
   when roadmap exits. The preferences file contains all the preferences
   items, and can be edited by the user. The schema file describes the
   geographic entities that are shown on the map; it should normally not be
   modified by the users. The sprites file contains the graphical definition
   of the symbols usd by RoadMap to indicates the various locations, to draw
   the compass, etc..

   The toolbar files define the content of the RoadMap and RoadGps toolbars.
   See the section CONFIGURING THE TOOLBAR for more information.


* CONFIGURING THE TEXT AND VOICE MESSAGES
   
   The RoadMap text displays and voice messages can be configured by the
   user using format strings in the preferences. The format strings contain
   static and dynamic parts. The dynamic parts (or "macros") are specified
   using the character '%' followed by one character that denotes a predefined
   RoadMap variable.

*-----+-----------------------------------------------------------------+
|  A: | estimated time of arrival (not yet implemented).
*-----+-----------------------------------------------------------------+
|  B: | Route bearing (not yet implemented).
*-----+-----------------------------------------------------------------+
|  C: | the name of the city for the selected or current street.
*-----+-----------------------------------------------------------------+
|  D: | Distance to the destination time (set only when a trip is active).
*-----+-----------------------------------------------------------------+
|  E: | Next sunset time (evening), undefined in night time.
*-----+-----------------------------------------------------------------+
|  F: | the full name (number, name, city) of the selected or current street.
*-----+-----------------------------------------------------------------+
|  H: | Altitude (set only when a trip is active).
*-----+-----------------------------------------------------------------+
|  M: | Next sunrise time (morning), undefined in daylight time.
*-----+-----------------------------------------------------------------+
|  N: | the name of the selected or current street.
*-----+-----------------------------------------------------------------+
|  S: | Speed (set only when a trip is active).
*-----+-----------------------------------------------------------------+
|  T: | Current time, format HH:MM (set only when a trip is active).
*-----+-----------------------------------------------------------------+
|  W: | Distance to the next waypoint (set only when a trip is active).
*-----+-----------------------------------------------------------------+
|  #: | the street number range to the selected or current street block.
*-----+-----------------------------------------------------------------+
   
   Note that the time is always shown using the military format: HH:MM.

   Example: "%D (%W)" shows the distance to the destination point, followed
   by the distance to the next waypoint (in parenthesis).
   
   A message is evaluated, and displayed, only when all referenced macros
   have a defined value. Therefore the example above will show nothing if
   there is no trip active, or if there is no next waypoint. It is possible
   to define several alternatives, separated by the character '|': the first
   alternative that has been successfully evaluated will be displayed.
   
   Example: "%D (%W)|%D" shows both distances to the destination point and
   to the next waypoint if both distances are defined, or else only the
   distance to the destination point if this distance is defined. If none
   of the two distance have been defined (for example when no trip is
   active), then no display is shown and/or no sound is produced.

   Another typical example is "sunset: %E|sunrise: %M", which shows the
   next sunset (in daylight time) or sunrise (in night time).

   It is possible to "link" together parts of a string using simple or
   double quotes. This is used when the string specifies an external command
   to execute. RoadMap does not use the shell to execute commands (so to stay
   independent from the OS-specific shell syntax), but it does recognise the
   use of quotes to specify a command parameter that includes spaces. Such
   a parameter may be enclosed in single or double quotes. There is no
   difference between one quote or another, except that the parameter must
   be terminated with the same quote character it was started with.
 
   Example: "flite -t 'On %N'" to specify the command flite with two
   parameters ("-f" and "On %N").


* CONFIGURING THE TOOLBAR

   The items shown in the RoadMap and RoadGps toolbars can be redefined by
   the user in a toolbar configuration file. Note that each program comes
   with a built-in toolbar configuration that serves as the default, so no
   toolbar file is required to be present for RoadMap or RoadGps to work.

   The major reason for customizing a toolbar is to let the user tailor
   the toolbar to fill small screens (such as a PDA) with his preferred
   controls.

   Each toolbar item is described by its action name. A separator is
   described by the character '-'. There must be only one item (action name
   or separator) per line. Empty and comment lines are authorized, comment
   lines start with the '#' character.

   The toolbar configuration file for RoadMap is named "roadmap.toolbar"
   and the one for RoadGps is named "roadgps.toolbar".

   There is a different list of possible actions for RoadMap and RoadGps.
   The list of valid action names can be obtained using the command line
   option --help=actions:

----
        roadmap --help=actions
        roadgps --help=actions
----

   The following is an example of a toolbar definition file for RoadMap:

----
        full
        quit
        -
        destination
        location
        gps
        hold
        -
        zoomin
        zoomout
        zoom1
----


* A NOTE REGARDING COLORS

   Some RoadMap configuration items define colors to be used. As a general
   rule a color must be described in a way that is suitable for the target
   graphic system.
   
   In the case of X11, that means either a color name (as defined in the
   /etc/X11/rgb.txt) or a color definition: #rrggbb where rr, gg and bb
   are hexadecimal values (for example: #FFFFFF is white, #000000 is black).

   Note that the #rrggbb format is broadly supported, even on target systems
   that do not support named colors.


* PREFERENCE ITEMS

    [General.Unit] The unit system used, either "imperial" or "metric"

         <<Default:>> imperial

    [General.Default Zoom] The zoom level when roadmap is started.

         <<Format:>> integer

         <<Default:>> 60

    [General.Keyboard] Show (yes) or hide (no) a keyboard on the screen.

         <<Format:>> boolean

         <<Default:>> yes

    [General.Icons] Show (yes) or hide (no) the roadmap icons.

         <<Format:>> boolean

         <<Default:>> yes

         <<Command line option:>> --no-icon

    [General.Toolbar] Show (yes) or hide (no) the roadmap toolbar.

         <<Format:>> boolean

         <<Default:>> yes

         <<Command line option:>> --no-toolbar

    [Geometry.Main] Sets the size of the RoadMap main window.

         <<Format:>> <WIDTH>x<HEIGHT>

         <<Default:>> 800x600

    [Geometry.WINDOW] Sets the size of the RoadMap window named WINDOW.

         <<Format:>> <WIDTH>x<HEIGHT>

         <<Default:>> 300x200

    [Display.Bottom Right] Defines the message on the bottom right corner.

         <<Format:>> RoadMap format string

         <<Default:>> %D (%W)|%D

    [Display.Bottom Left] Defines the message on the bottom left corner.

         <<Format:>> RoadMap format string

         <<Default:>> %S

    [Display.Top Right] Defines the message on the top right corner.

         <<Format:>> RoadMap format string

         <<Default:>> ETA: %A|%T

    [Display.Duration] The time during which a selection or message is shown.

         <<Format:>> number of seconds.

         <<Default:>> 10

         <<Comment:>> the selection is only removed when the map is redrawn.

    [Display.Rotate] Does the display rotate when tracking mobile objects?

         <<Format:>> boolean

         <<Default:>> "yes"

    [Help.Browser] The browser program used to show the help text.

         <<Format:>> a program name, with or without path.

         <<Default:>> dillo

    [Help.Arguments] The browser's command line arguments

         <<Format:>> a format string, with one '%s' for the help URL.

         <<Default:>> %s

    [Map.Path] The map database search path.

         <<Format:>> a comma-separated list of directory paths.

         <<Default:>> ~/.roadmap/maps,/var/lib/roadmap,/usr/lib/roadmap

         <<Comment:>> the default also includes /usr/local/share/roadmap
                      and /usr/share/roadmap, for compatibility purposes.
                      These two directories were the standard locations
                      for the maps in previous versions of RoadMap.

    [Map.Cache] The number of entries in RoadMap's mapping cache.

         <<Format:>> integer

         <<Default:>> 8

    [Map.Background] The color used for the background of the maps.

         <<Format:>> color

         <<Default:>> LightYellow

    [Map.Signs] Enable/disable the map sprites and street signs.

         <<Format:>> boolean

         <<Default:>> yes

         <<Comment:>> use only in special cases (very small screens)

    [Map.Refresh] Forces a screen refresh every time.

         <<Format:>> enumeration (normal / forced)

         <<Default:>> normal

    [GPS.Background] The background color for the RoadGps screen.

         <<Format:>> color

         <<Default:>> LightYellow

         <<Comment:>> this color is used by RoadGps, not by RoadMap.

    [GPS.Foreground] The foreground color for the RoadGps screen.

         <<Format:>> color

         <<Default:>> Black

         <<Comment:>> this color is used by RoadGps, not by RoadMap.

    [GPS.Timeout] A timeout for detecting that the GPS link is down.

         <<Format:>> number of seconds.

         <<Default:>> 10

         <<Comment:>> the GPS link is considered down if no new GPS data was
                  received for the specified amount of time.

    [GPS.Source] The URL that gives the address of the GPS data source.

         <<Format:>> <protocol>:<description>

         <<Default:>> gpsd://localhost

         <<Comment:>> The gpsd protocol (gpsd://<hostname>[:<port>]) uses
                  the NMEA raw mode of gpsd, while the gpsd2 protocol
                  (gpsd2://<hostname>[:<port>]) uses the gpsd native protocol.
                  The object protocol (object:<id>) makes it possible to use
                  an internal RoadMap object as GPS source (so that a driver
                  can feed the GPS position to RoadMap).
                  The file protocol (file://<path>) is also possible, for debug.

    [GPS.Color] The color used for the current GPS position symbol.

         <<Format:>> color

         <<Default:>> green

         <<Comment:>> this color is used by RoadMap, not by RoadGps.

    [Destination.Color] The color used for the destination symbol.

         <<Format:>> color

         <<Default:>> red

    [Selected Street.Background] The color for the background of the selected
         street name.

         <<Format:>> color

         <<Default:>> yellow

    [Selected Street.Foreground] The color for the foreground of the selected
         street name.

         <<Format:>> color

         <<Default:>> black

    [Selected Street.Text] The format used for the selected street's display.

         <<Format:>> RoadMap format string

         <<Default:>> %F

    [Console.Background] The color used for the background of the trip display.

         <<Format:>> color

         <<Default:>> yellow

    [Console.Foreground] The color used for the foreground of the trip display.

         <<Format:>> color

         <<Default:>> black

    [Current Street.Background] The color for the background of the current
         street's name.

         <<Format:>> color

         <<Default:>> DarkSeaGreen4

    [Current Street.Foreground] The color for the foreground of the current
         street's name.

         <<Format:>> color

         <<Default:>> white

    [Current Street.Text] The text used to display the current street's name.

         <<Format:>> color

         <<Default:>> black <(I would recommend using white--see above)>

         <<Default:>> %N, %C|%N

    [Voice.Current Street] The command used to announce the current street's
         name.

         <<Format:>> RoadMap format string

         <<Default:>> flite -t 'On %N'

    [Voice.Selected Street] The command used to announce the selected street's
         name.

         <<Format:>> RoadMap format string

         <<Default:>> flite -t '%N'

    [Voice.Next Intersection] The command used to announce the name of the
           next intersection.

         <<Format:>> RoadMap format string

         <<Default:>> flite -t 'Next intersection: %N'

    [Voice.Approach] Reserved for future use (approaching waypoint).

    [Accuracy.Confidence] The minimum rating for a street to be selected

         <<Format:>> integer, range 0 .. 1024

         <<Default:>> 25

         <<Comment:>> RoadMap uses fuzzy logic to identify what street
                  the vehicule is on. This value if a minimum fuzzy result
                  for RoadMap to select any street. This helps not selecting
                  whatever street is near by when off-road. This also speeds
                  up the identification process by filtering out unlikely
                  matches.

    [Accuracy.GPS Position] The GPS's estimated position error (worst case)

         <<Format:>> integer

         <<Default:>> 300

         <<Comment:>> the unit depends on the selected unit system (feet or
                  meter). The default shown being tuned for feet. This default
                  accuracy can be adjusted to the actual GPS estimate if a
                  Garmin GPS receiver is used.

    [Accuracy.GPS Speed] GPS's speed accuracy.

         <<Format:>> integer

         <<Default:>> 4

         <<Comment:>> the unit depends on the selected unit system (ft/s or
                  m/s).

    [Accuracy.Mouse] The size of the street selection search area.

         <<Format:>> number of pixels

         <<Default:>> 20

         <<Comment:>> on a mouse click, RoadMap defines the street search area
                  as the rectangle delimited by the two points
                  (x-accuracy, y-accuracy) and (x+accuracy, y+accuracy).
                  Limiting the search to this area speeds up the process,
                  compared to searching in the whole screen area.

    [Accuracy.Street] The street selection accuracy.

         <<Format:>> integer (using the current unit system).

         <<Default:>> 150

         <<Comment:>> This is the maximum distance to a street for the
                  navigation logic. If a street is at a distance greater than
                  this value, then RoadMap will never consider this street
                  when searching which street the vehicule is on.

    [History.Depth] The maximum number of items in the <<find>> history.

         <<Format:>> integer

         <<Default:>> 100

    [Approach.Background] Reserved for future use (approaching waypoint).

    [Approach.Foreground] Reserved for future use (approaching waypoint).

    [Approach.Text] Reserved for future use (approaching waypoint).

    [Download.Source] The format used to generate the URL of the source.

         <<Format:>> printf() format, which must include the sequence "%05d".

         <<Default:>> /usr/local/share/roadmap/usc%05d.rdm

         <<Comment:>> this item is either a full path name (starting with a '/')
                  or an URL (such as "file://[...]" or "http://[...]").

    [Download.Destination] The path of the directory where to store the
         downloaded map files.

         <<Format:>> string

         <<Default:>> &/maps

         <<Comment:>> this item must be either a full path name or start with
                  '~' (user home directory) or '&' (RoadMap user's directory).

    [Style.Use Pretty Lines] If "yes", roads are shown with all the defined
          pens (see schema). If "no", roads are shown with the first pen only.

         <<Format:>> boolean

         <<Default:>> "yes"

    [Style.Pretty Lines when Dragging] If "yes", roads are shown with all the
          defined pens when dragging (if enabled--see above). If "no", roads
          are shown with the first pen only while dragging.

         <<Format:>> boolean

         <<Default:>> "yes"

    [Style.Show Objects when Dragging] If "yes", objects are shown when
          dragging. If "no", objects are not shown while dragging. Objects
          are the sprites, text messages, etc..

         <<Format:>> boolean

         <<Default:>> "yes"


* SESSION ITEMS

    [Location.Position] The latest selected position.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

         <<Comment:>> the name of this item is kind of silly, to be changed.

         <<Command line option:>> --location=<LONGITUDE>,<LATITUDE>

    [GPS.Position] The latest received GPS position.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

    [GPS.Direction] The latest received GPS direction.

         <<Format:>> degrees

         <<Default:>> 0

    [Selection.Position] The position of the latest selection.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

    [Address.Position] The position of the latest address used.

         <<Format:>> longitude ',' latitude.

         <<Default:>> -122394181,37794928

    [Trip.Name] The name of the last used trip file.

         <<Format:>> string

         <<Default:>> default
         
    [Delta.X] The horizontal map shift compare to the reference position.

         <<Format:>> number of pixels

         <<Default:>> 0

    [Delta.Y] The vertical map shift compare to the reference position.

         <<Format:>> number of pixels

         <<Default:>> 0

    [Delta.Rotate] The rotational shift compare to the reference direction.

         <<Format:>> degrees.

         <<Default:>> 0

    [General.Zoom] The current zoom level.

         <<Format:>> number

         <<Default:>> see the default zoom preference item.

    [Focus.Rotate] Indicate if the current map focus is set to rotate.

         <<Format:>> boolean (1 or 0)

         <<Default:>> 0

    [Focus.Name] Name of the reference position where the focus should be set.

         <<Format:>> either "GPS", "Location" or "Address"

         <<Default:>> "Location"

    [Navigation.Enable] Defines if the roadmap navigation function is enabled.

         <<Format:>> boolean

         <<Default:>> "yes"

    [Voice.Mute] Defines if the voice function was muted by the user.

         <<Format:>> boolean

         <<Default:>> "no"

    [Hold.Direction] An artefact of saving the context. Ignored.

    [Hold.Position] An artefact of saving the context. Ignored.

    [Log.Path] Last selected path for the RoadGps log files.

         <<Format:>> a directory path.

         <<Default:>> /var/tmp

 (*) NOTE: the default position values match 1 Market St, San Francisco, CA.


* SCHEMA ITEMS

     The schema file uses the same format as the preference file. It defines
     the properties of the various categories of objects that make a map.
     the list of categories matches the list of Tiger file's categories
     (see Tiger's CFCC field) that have been filtered by buildmap.

     The two differences with the preferences files are that there is no
     pre-defined category in RoadMap: categories are defined by the maps
     (FIXME: this is still to be done--as a temporary hack, the categories
     have been hardcoded somewhere) and there is no default value.

     For each category, RoadMap use the following items:

     [<category>.Class:] the class of object this category belongs to.

         <<Format:>> Road, Feature or Area.

         <<Comment:>> Road and Feature categories are searched in the "line"
                  table of the map files and drawn as lines. The Road
                  category is searched when a street name is looked for.
                  The Area objects are drawn separatly, as polygons.

     [<category>.Color:] the color used when drawing the objects.

         <<Format:>> color

     [<category>.Declutter:] the zoom level from which the objects are hidden

         <<Format:>> integer

         <<Comment:>> the definition of this item is rather obscure. To be fixed.

     [<category>.Thickness:] the thickness used to draw lines.

         <<Format:>> number of pixels


   RoadMap uses the following categories:

         * Freeways

         * Ramps

         * Highways

         * Streets

         * Trails

         * Rivers

         * Shore

         * Hospitals

         * Malls

         * Airports

         * Stations

         * Lakes

         * Parks

         * Sea


* SPRITES FILE

     This file defines the drawing commands used to draw the various symbols
     used by RoadMap:

         GPS (indicates the current GPS position and direction),
         Position (indicates the currently selected location),
         Destination,
         Highlight (marks the endpoints of a selected street block) and
         Compass (used to indicates the direction of the North pole).

     The sprites file is made of a sequence of single-line commands:

*------------------------------+---------------------------------------------+
|        S <name>              | Starts a sprite.
*------------------------------+---------------------------------------------+
|        F <color> <thickness> | Define the pen to be used by the subsequent
|                              | drawing commands.
*------------------------------+---------------------------------------------+
|        L <x>,<y> ..          | Draw a line.
*------------------------------+---------------------------------------------+
|        P <x>,<y> ..          | Draw a filled polygon.
*------------------------------+---------------------------------------------+
|        C <x>,<y> <radius>    | Draw a circle.
*------------------------------+---------------------------------------------+
|        D <x>,<y> <radius>    | Draw a disk (filled circle).
*------------------------------+---------------------------------------------+

     The coordinates are pixel positions, relative to the sprites "hot point".


* TRIP FILES
   
     A trip file contains the information relative to one trip. it uses
     a CSV format where each record describes a point and contains four
     fields: type, name, longitude, latitude.
     
     The type field is either "Destination" or "Waypoint".
     
     The name field is the name of the waypoint (the name of the destination
     is always "Destination").

     The following trip file example defines a trip from the Golden Gate's
     bridge to 1, Market St, in san Francisco, California:
     
+-------------------------------------------------------
     Destination,Destination,-122394181,37794928
     Waypoint,1000 - 1098 The Embarcadero  San Francisco,-122401781,37803934
     Waypoint,100 - 198 Richardson Ave  San Francisco,-122446481,37799826
+-------------------------------------------------------


TOOLS

   A RoadMap map file is a small database of C tables. The tables are organized
   in a tree fashion and each table is identified by a path. One specific set
   of tables (the dictionary) groups all the names that appear in the map.

   RoadMap comes with a tool to display information extracted from a map file:

   dumpmap [--usage] [-d TABLE] [--strings] [--volume=NAME] [--search=NAME]

   dumpmap uses the popt library for parsing command line argument: the
   option --help provides a full description of each option. The name of
   map files must be provided after the options: dumpmap will process each
   provided file sequentially, according to the options that was selected.


CONFIGURATION EXAMPLES

   ~/.roadmap/preferences ("factory" defaults):

+-------------------------------------------------------
Accuracy.Confidence: 25
Accuracy.GPS Position: 300
Accuracy.GPS Speed: 4
Accuracy.Mouse: 20
Accuracy.Street: 150
Approach.Background: yellow
Approach.Foreground: black
Approach.Text: Approaching %N, %C|Approaching %N
Console.Background: yellow
Console.Foreground: black
Current Street.Background: yellow
Current Street.Foreground: black
Current Street.Text: %N, %C|%N
Destination.Color: red
Display.Bottom Left: %S
Display.Bottom Right: %D (%W)|%D
Display.Top Right: ETA: %A|%T
Display.Duration: 10
Display.Rotate: yes
General.Default Zoom: 20
General.Keyboard: no
General.Toolbar: yes
General.Icons: yes
General.Unit: imperial
Geometry.Main: 800x600
Geometry.Preferences: 800x300
GPS.Background: LightYellow
GPS.Color: red
GPS.Foreground: black
GPS.Source: gpsd://localhost
GPS.Timeout: 10
History.Depth: 100
Map.Path: ~/.roadmap,/var/lib/roadmap,/usr/lib/roadmap
Map.Cache: 8
Map.Background: LightYellow
Map.Refresh: normal
Map.Signs: yes
Polygons.Declutter: 1300
Selected Street.Background: yellow
Selected Street.Foreground: black
Selected Street.Text: %F
Shapes.Declutter: 1300
Voice.Approach: flite -t 'Approaching %N'
Voice.Current Street: flite -t 'On %N'
Voice.Next Intersection: flite -t 'Next intersection: %N'
Voice.Selected Street: flite -t '%N'
+-------------------------------------------------------


   ~/.roadmap/session ("factory" defaults):

+-------------------------------------------------------
Locations.Location: -122394181,37794928
Locations.GPS: -122394181,37794928
Locations.Trip: default
General.Zoom: 0
Navigation.Enable: yes
Delta.X: 0
Delta.Y: 0
Delta.Rotate: 0
GPS.Position: 0,0
GPS.Direction: 0
Address.Position: 0,0
Selection.Position: 0,0
Hold.Position: 0,0
Hold.Direction: 0
Focus.Rotate: 1
Focus.Name: GPS
Trip.Name: default
+-------------------------------------------------------


IMPLEMENTATION DETAILS

   This section contains additional information for developpers, knowledge
   that is not required for using RoadMap. It is here to answer some usual
   questions and help people who want to hack with the RoadMap code.


* PORTING ROADMAP

   The roadmap and roadgps applications have been designed so to facilitate
   portability. Two sub-parts of RoadMap have been isolated for that purpose:
   the graphic user interface and the OS interface.

   The graphic user interface is all defined by the following header files:

     [roadmap_main.h]          The application's main window.

     [roadmap_canvas.h]        The canvas used to draw the map.

     [roadmap_dialog.h]        The widget used to build dialogs.

     [roadmap_messagebox.h]    A pre-built warning/error dialogs.

     [roadmap_fileselection.h] A pre-built file selection dialog.

   The OS interface is defined by the following header files:

     [roadmap_net.h]           Isolate socket interface oddities.

     [roadmap_path.h]          Hides the OS syntax for file path.

     [roadmap_file.h]          Primitives to access and map binary files.

     [roadmap_time.h]          Primitive to get the local time.

     [roadmap_spawn.h]         Hides the OS process control.

     [roadmap_library.h]       Load and link to dynamic libraries (future).

   Implementations of the user interface for the GTK, GTK2 and Qt toolkits
   are provided, as well as one implementation of the OS interface for UNIX.

   Porting RoadMap to a new environment probably means to adapt the RoadMap
   make files and write new implementations for the functions defined in
   the header files listed above.


* PROJECTION

   The maps used by RoadMap define all points using longitude/latitude
   coordinates (WGS 84 datum). This means the coordinates describe the
   position of the point on a reference elipsoid (as close to the Earth's
   potatoe-like shape as scientifically possible). On the other side the
   Computer (or PDA) screen is still a plane. Converting a longitude and
   latitude coordinate into a plane X/Y coordinate is traditionally called
   a "projection". There are several standard projection methods. RoadMap
   uses none of them that I know of.

   RoadMap first approximates the WGS 84 elipsoid to a sphere. Then it
   considers the point at the center of the screen and compute the scale
   at that point (i.e. delta(x)/longitude and delta(y)/latitude. After that
   the local area is approximated to the plane that is tangent to the sphere
   on that center point. Therefore a new projection is defined each time a
   new screen is drawn. Also the distorsion is probably very significant
   when zooming out. It is possible to zoom out to the point of seeing
   the full continental US on the screen, and it is still recognizable.
   This way of doing things seems to perturbate many people familiar with
   map projections..

   The RoadMap projection has one major advantage: after the scale has been
   computed (once per screen refresh), the only transformation left is
   a simple and fast "(center - position) * scale" conversion. There are
   two scales: one for longitude and one for latitude (the longitude's
   scale depends on the latitude). Most operations are performed using
   integer operations, including the pre-computed sine and cosine tables,
   so that RoadMap has decent performance on integer-only processors (such
   as most of the ARM CPUs). In order to do so the (precomputed) sine and
   cosine table has values that have been multiplied by 32768 and the final
   scale is being divided by 32768.
   
   This projection was chosen because of its speed, not really for its
   accuracy. As the Earth is not exactly a sphere, and certainly far from
   a plane, the RoadMap projection is going to cause a measurable distorsion.
   This is not a significant issue in RoadMap for several reasons:

    * most users are concerned with very small areas (a few street blocks),
   and the map distorsion is not going to be noticeable at this scale.

    * the schematic representation of the streets and geographical features
   is more important than a geometrically correct drawing.

    * the GPS position is also provided using WGS 84 coordinates and the same
   projection algorythm is used to represent the GPS position on the screen.
   The same distorsion effect applies to the GPS position, and thus the GPS
   position is correct relative to the street (at least when not considering
   map accuracy problems..).


WRITING A ROADMAP DRIVER

* OVERVIEW

   A RoadMap driver is a standard UNIX program that interacts with RoadMap
   using the standard input and output. There is no need to link to a specific
   RoadMap library, even while this is not forbidden either.
   
   RoadMap launches each driver with its standard I/O redirected to pipes.
   The driver program must exit when any of these pipes breaks.

   The protocol between RoadMap and the drivers uses the NMEA syntax, with
   one NMEA standard sentence and some RoadMap-specific extensions. The
   general design is that the driver takes the initative and RoadMap answers.

   It is possible to write a driver that can be launched multiple times by
   RoadMap. The only requirement is to associate a different driver name to
   each occurrence in the drivers file. It is recommended the driver takes
   its name from its command line, using the following syntax:
   
----
       --driver=<name>
----

   It is also recommended that the driver name be used as the preferences
   category when requesting a driver's specific preferences items. The makes
   it possible to configure each occurrence of the driver independently.

   See roadmap_ghost.c for an example of a minimal RoadMap driver.


* DRIVER COMMANDS

----
       $PXRMCFG,<category>,<name>,<default>
----

   This sentence requests the value of the provided RoadMap preferences
   item. If the item is ot defined, RoadMap will answer with the default
   value provided. The RoadMap's answer uses the exact same syntax, where
   the default value is replaced with the actual value.

   There is no need to declare a preferences item in advance: RoadMap
   will declare the item on the fly.

----
       $PXRMSUB,<item>,...
----

   This sentence requests RoadMap to send periodic updates of the specified
   items. Each command adds to the subscription list: there is no way to
   unsubscribe. The subscription items supported by RoadMap are:

        * RMC: requests RoadMap to transmit every change to its current GPS
          position. The RoadMap position is sent as a NMEA $GPRMC sentence.

----
       $PXRMADD,<id>,<name>,<sprite>
----

   This sentence requests RoadMap to record a new object to its tracking
   list. The object is identified by it's ID. The name and the sprite are
   used for display. The sprite must have been defined in RoadMap's sprites
   file.
   
   A newly created object has no position. This object will not appear on
   the screen until a position has been provided.

----
       $PXRMMOV,<id>,<latitude>,<N|S>,<longitude>,E|W,<speed>,<steering>
----

   This sentence associates a new position to the specified object. There
   is no limit on how many times the position of an object can be changed.
   The syntax for the position mimics the syntax used in GPRMC, except that
   the speed and steering must be integers (no fractional part).

----
       $PXRMDEL,<id>
----

   This command requests RoadMap to delete the specified object.


* ROADMAP RESPONSES

----
       $PXRMCFG,<category>,<name>,<value>
----

   This sentence is the answer to the driver's $PXRMCFG requests. The
   only difference compare to the request is that the default value has
   been replaced with the actual value.

----
       $GPRMC,<time>,<latitude>,<N|S>,<longitude>,E|W,<speed>,<steering>,
              <UTC date>,0,E
----

   This sentence is the answer to the driver's subscription to the RMC item.
   It uses the standard NMEA syntax, except that the speed and steering are
   integers (no fractional part), while the magnetic variation is always 0.


MAP FORMAT

* MAP FILES

   As indicated in several other places, the RoadMap map files (extension
   .rdm) are organized by county (one file per county), plus a directory
   of counties (usdir.rdm). The name of a county file follows the format:

----
   usc<fips>.rdm
----

   where "fips" is the federal identification number for that county, made
   of five digits: the first two digits identify the state and the last
   three digits identify the county within the state.

   The rdm files are binary files and uses the local conventions for byte
   order and C structure layout.

   The two types of files, usdir.rdm or usc*.rdm, contain very different
   data but share the same general organization: these files contain
   multiple data tables organized in a tree fashion.

* TABLES

   Each table is identified by its path name (such as "string.data.data").
   RoadMap tables are organized into two levels, except for the string
   storage tables that are organized into three levels.
   
   The dumpmap tool provides a view of the tree of tables.

   Each table is an array of C structures. As the map files are being
   mapped in memory, RoadMap will access these C structure as if it was
   a regular C array created by the program.

   Each top level section is managed by a specific RoadMap module (usually
   one source file) that retrieves all tables within the given top level
   by name. If one table is missing, RoadMap will exit with a fatal error
   but it is legal to have additional tables: these will simply be ignored.

   Thus it is not required to know the exact details of the map format
   in order to be able to access the map information: each module hides
   the specifics of the section it handles. It is however be necessary
   to understand the logic organization of the map data in order to be
   able to navigate through it.

   Each top level section is also created by a specific buildmap module
   (usually a single source file as well). These modules are totally
   independent from the format of the original data and should be usable
   for creating RoadMap map files from other data sources.

   Thus there is no need to know the inner details of the RoadMap map format
   in order to generate a map file: the buildmap_* modules handle the
   implementation details for each section, including sorting and indexing.

   All sections are described using the same descriptor structure (see
   roadmap_db.h) and are organized in a "Russian doll" fashion, i.e.
   the data area described in a given section covers all subsections
   (descriptor plus data area). The toplevel section are actually
   subsections of an anonymous root section, which descriptor starts
   at offset 0.

* THE STRING SECTION

   All files contain a "string" top level section. This section stores
   all texts associated with other records. Its purpose is to handle
   variable length text in the most compact way, i.e. using no more than
   the storage needed for the C string (string length plus terminator)
   and avoiding repeating identical texts. When the string tables is built
   all identical texts should be identified and each text stored only once.

   In addition, the string section provides a search tree organized in
   an alphabetical fashion. This tree makes it possible to implement fast
   name search and completion and was also designed to allow for a "smart"
   keyboard that grays out invalid characters (the "smart" keyboard was
   never implemented since RoadMap now uses the standard system keyboard).

   The string section is organized in string categories (city names, street
   names, etc..). All categories are organized with the same tables:

   [tree]         this table contains the branches of the search treeindex.

   [node]         this table contains the leaves of the search tree.

   [index]        this table contains a relative index to the actual
                  storage location of the string. Its purpose is to
                  allow the use of a 16 bit identifier instead of using
                  a 32 bit offset.

   [data]         This table is really a byte buffer that contains the
                  actual strings.

   The string section is handled in RoadMap by the roadmap_dictionary.c
   module and created by the buildmap_dictionary.c module (see matching
   header files roadmap_dictionary.h and buildmap.h for more information
   about the API).

* DIRECTORY TABLES

   The usdir.rdm file is made of the "string" and "county" sections.
   The "county" section provides a spatial and city search index for
   selecting maps involved in an address search or for visualization.

   When an address is provided, RoadMap scans through the "county.bystate"
   and "county.city" tables to retrieve which counties might include a
   city by the given name. In order to separate homonymous cities in
   different states and accelerate the search, the cities are sorted by
   state and the table "county.bystate" points to the sub-table that covers
   each state. Thus the logic is to identify the state (sequential search)
   and then scan through the state's city sub-table to retrieve the city
   name. Remember that the city names are really stored in "string.city":
   "county.city" only contains the index to the city name (a 16 bit value).
   This also speeds up the search.

   When a position (longitude, latitude) is provided, RoadMap scans through
   the "county.bystate" abd "county.data" tables. Once again, "county.data"
   is sorted by state and "county.bystate" indicates the matching sub-table.
   Both states and counties are located by there "bounding box", i.e. the
   area defined by the most southern and northern points and the most
   eastern and western points.

   Thus RoadMap searches for all states that may cover the given location,
   then through the associated "county.data" sub-table to search for the
   counties that may covert the given location.

   In most cases a position is actually itself the area visible on the
   screen rather than a single point. That however does not change the
   logic in any fundamental way: the only difference is that "coverage"
   is defined as a non-empty intersection between the two areas (visible
   v.s. bounding box).

* MAP TABLES

   The county map files are organized into the following sections:

   [string]       See prior description in this document. This section
                  is defined in the roadmap_db_dictionary.h header,
                  handled by the roadmap_dictionary.c module and created
                  by the buildmap_dictionary.c module.

   [square]       Each county is subdivided using an evenly defined grid.
                  Each element of the grid (square) is a rectangle in the
                  longitude / latitude coordinate system.  This section is
                  defined in the roadmap_db_square.h header, handled by the
                  roadmap_square.c module and created by the buildmap_square.c
                  module.

   [point]        A spatially sorted list of position points used to
                  define lines an polygonal areas. This section is defined
                  in the roadmap_db_point.h header, handled by the
                  roadmap_point.c module and created by the buildmap_point.c
                  module.

   [line]         The description of lines (mostly street block). A line
                  is defined by two points and a type (intertate, street,
                  shoreline, etc..) This section is defined in the
                  roadmap_db_line.h header, handled by the roadmap_line.c
                  module and created by the buildmap_line.c module.

   [shape]        Additional points that define the shape of lines. Not
                  all lines have a shape: straight lines don't. This
                  section is defined in the roadmap_db_shape.h header,
                  handled by the roadmap_shape.c module and created by
                  the buildmap_shape.c module.

   [polygon]      The description of areas (parks, hospitals, airports,
                  malls, etc..). A polygon is defined as a list of points.
                  This section is defined by the roadmap_db_polygon.h
                  header, handled by the roadmap_polygon.c module and
                  created by the buildmap_polygon.c module.

   [street]       Full streets, i.e. a collection of lines sharing the
                  same street name in the same city (and same ZIP code).
                  This section is defined in the roadmap_db_street.h
                  header, handled by the roadmap_street.c module and
                  created by the buildmap_street.c module.

   [range]        A set of index tables to speed up the search of a
                  street address. This section is  defined in the
                  roadmap_db_range.h header, handled by the roadmap_street.c
                  module (not a typo !) and created by the buildmap_range.c
                  module.

* THE SQUARE SECTION

   Each county is divided in tiles (called quite improperly "squares").
   Most data (point, lines and polygons) are sorted by square and indexes
   allow to access only the sub-table related to one square. The purpose
   of the square design is to speed up drawing and research (scan smaller
   amount of data), avoid page fault, limit the process memory use to the
   local vicinity information as well as reduce the size of the maps by
   using 16 bit relative positions instead of 32 bit absolute ones.

   The squares are generated by buildmap so that each square is small
   enough for a 16 bit longitude and latitude offset. All squares have
   the same "size" as expressed in longitude / latitude.

   In some case (Hawaii) the land is a very sparse subset of the grid,
   so the grid is described using a list of grids instead of a complete
   matrix. RoadMap regenerate the matrix when the file is mapped.
   Without that optimization Hawaii could not be handled.

   The square section is made of two tables: square.global and square.data.

   The global table contains only one record that stores the size of
   the matrix (in number of element) and the size of each element (as
   longitude and latitude offsets).

   The data table contains the position of each square as well as the
   number of points located in that square.

* THE POINT SECTION

   All points referenced by the lines and polygons are actually stored
   in this section. The shape are however different (not made of points,
   see later).

   The point section is made of two tables: point.data and point.bysquare.

   The data table contains the position of each point, relative to the
   south-west corner of its square. Which means you cannot know where
   a point is without knowing in which square it is.

   The bysquare table is an index to retrieve all points within a given
   square. The index in point.bysquare is the square index. All the points
   sorted so that all points within a given square are grouped. This
   format optimizes the search by square, which is the most used one (such
   as when drawing a map).

* THE LINE SECTION

   A line represents a street block, a section of freeway, a ramp, a section
   of shore, etc.. These lines are all listed in the same table and indexes
   allow for a fast access according to the location and type. A line is
   represented with two points: a "from" point and a "to" point. The choice
   of which point is the "from" is derived fro the corresponding line
   definition in the map's original source format (usually the first point
   listed is the "from" point).

   The line section is made of the following tables: line.data, line.bysquare,
   line.bysquare2 and line.index2.

   The data table contains the reference to the two end points of the line.
   Note that the shape is stored separately. Lines are sorted by square and
   type.

   The bysquare table references the sub-table that represents all the lines
   in the given square. Each record actually contains as many references as
   there are possible line type: it references each sub-table that represents
   the lines of a given type in the square. This speeds up drawing as all
   the lines of a given type are in the same layer, using the same video
   attributes (color, thickness, etc..) and are displayed at the same time.

   The bysquare2 and index2 tables are used to identify these lines that
   cross square limits, i.e. the lines that have their two endpoints in
   two different squares. Table bysquare2 is identical to bysquare, except
   it references table index2 instead of table data. The table index2 contains
   the index to the data table. This indirection is needed because the lines
   have been sorted according to their "from" endpoint, not by their "to"
   endpoint.

* THE SHAPE SECTION

   A shape contains the middle points needed to represent curved lines.
   These middle points are not regular points because they connect nothing
   together and do not participate into the map's logical organization: the
   shapes are only useful to display a more accurate drawing of the
   associate line. It has no function beyond just look.

   The middle points are represented using 16 bit relative offsets from each
   others, starting with the line's "from" endpoint. If two middle points are
   too far from each other the buildmap_shape.c module will automatically
   create additional middle points, as many as required to comply with the
   16 bit offset limitation.

   The shape section is made of the tables shape.bysquare, shape.byline
   and shape.data.

   The table data contains the list of middle points, sorted by square, line
   and order in the line. Thus all middle points required to represent a
   given line are grouped together and all lines within a given square are
   also grouped together.

   The table byline identifies the line (index into the line section, see
   above) and the list of middle points.

   The table bysquare points to the sub-table of byline that contains all
   the lines within the given square.

* THE POLYGON SECTION

   The polygon section describes features such as malls, airports, parks,
   lakes, etc..

   A polygon is represented by a list of lines that defines the area of
   the polygon (buildmap checks that the list of lines represents a valid
   and complete border).

   The polygon section contains the tables polygon.head and polygon.points.

   The points table lists the points that make the border of the area,
   grouped by polygon and sorted so to form a valid polyline fit for
   drawing the polygon. This table references points defined in the point
   section. The main reason d'etre for this table is the grouping and
   sorting: the points are not sorted using the same criteria as in the
   point section.

   The head table describe the polygon's bounding box, type, name, etc..
   It also point to the first and last point that defines its border.

   Note that polygons are not sorted by square, as there is no limit on
   how many squares a polygon could belong to. A use of a more traditional
   spatial index could have been useful here.. Note however that the number
   of polygons in a given county is relatively limited, so a more effective
   visibility search is not critical to RoadMap performances.
 
* THE STREET SECTION

   This section contains the tables street.name and street.type.

   The table name contains the references to all the elements of a street
   name: prefix (South, North, etc..), name, type (Road, Street, Lane, etc..)
   and suffix (South, North, etc..).

   The table type contains one-byte elements that indicates the type of
   line for that street (see the line section). This table is not used.

   The main reason d'etre for the street section is to gather togethers
   elements that are repeatitively referenced together in the range section.

* THE RANGE SECTION

   The range section describe the street addresses. This is the section
   the "find by address" feature of roadmap is based on. It also contains
   the name of those lines for which there is no address associated.

   The range section is made of the following tables:

   [range.bystreet]  for each street, the ranges that belong to the street.
   [range.bycity]    the list of ranges by street, brocken for each city.
   [range.addr]      for each range, the street address numbers.
   [range.noaddr]    reference to the street for the lines with no address.
   [range.byzip]     for each range, the ZIP code.
   [range.place]     for each place, the city it belongs to.
   [range.bysquare]  for each square, a street search accelerator.

