readme

A car navigation system for Unix and PocketPC.

   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]
----
   
   The format for latitude is:

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

   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 '-'.

   * 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. 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 will 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 selecting the "Trips / Resume Trip
   (North Up)" menu entry.

   The reserve trip always works in the same mode as previously selected
   the last time the trip was started or resumed: for example, if the "North
   Up" mode was selected when the trip was resumed, then the reverse trip
   will still use this "North Up" mode.


* 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