readme

A car navigation system for Unix and PocketPC.

            /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

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


* 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.
*-----+-----------------------------------------------------------------+
|  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").


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

    [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:>> gpsd://<hostname>[:<port>]

         <<Default:>> gpsd://localhost

         <<Comment:>> the syntax "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