Map Editing capabilities of Xrmap
=================================

Starting from version 2.20, xrmap allows user defined constructs and
therefore provides a possibility to add various types of features on 
the maps: icons, polygons, filled polygonal regions, etc. This can
be done either through the command line (at start-up or with the GUI),
or, in a much more comfortable way, through editing an 'rcfile' 
<name_of_file>.rc . The rcfile should contain all basic data
(colors, geographic position, projection mode, zoom factor, etc) 
*and* the additional user defined constructs.

It is now also possible to link an arbitrary system call to a mouse click
at a particular geographic location (e.g. displaying an image of the
Eiffel Tower when you click on Paris). Users of this feature should be
aware of the possible security implications in case they would use 
unverified rcfiles invoking unverified system calls -- for this purpose 
xrmap includes a '+secure' option so as to disable user defined system 
calls. The '+secure' option is not set by default, however. Unsetting
the '+secure' option is simply '-secure'.


I. User defined constructs through the command line
---------------------------------------------------

User defined objects are set or unset with

-define <feature_definition>
-undefine <rank>

(can also be abbreviated as '-def *' and '-undef *'). Each 'define'
creates a new line in the list of defines, and that line is numbered
according to its order of creation, starting with rank 0. Setting
'-undefine <rank>' has the effect of cancelling the feature of the 
given rank, and shifts down by one unit all subsequent ranks 
of features that were defined later.

As we already mentioned, the following option can be used to disable/reenable
system calls:

+secure   (resp.  -secure)


II. Editing a rcfile through a text editor
------------------------------------------

An easier way of editing the maps is to use a text editor to edit
directly the rcfile. Xrmap has a key shortcut '*' (asterisk) which has
the effect of dumping all map parameters into a temporary file
   /tmp/XXXXX_xrmap.rc 
This file is then loaded into a text editor and can thus be modified. 
By default, 'emx', a lightweight emacs clone contained in the distribution
is used as the editor. With 'emx' the Alt-M key is bound to running
'xrmap -rcfile /tmp/XXXXX_xrmap.rc', thus displaying the map with the
given -- and possibly new -- features.

The rcfile consists of 3 sections looking like this

<colors>
00 + grey40
01 + grey55
02 + grey70
...
47 + red
48 + yellow4

<parameters>
-projection 0 -zoom 8.000000
-width 672 -height 672 -aspect 1.000000 -accuracy 1.000000
...
-locfilter BCIKLORSTV*

<defines>
color|blue
font|1
region|45.0,2.0|46.1,3.2|44.2,2.2
exec|2|48.860,2.340|xv eiffel.jpg

The 4 defines abowe (see the precise syntax in section III) will :
* select blue as the default drawing color, 
* select font 1 as the font to be used with user defined labels
* create a filled polygonal region somewhere in France (with 3 vertices, 
  so it's actually a triangle!)
* link a mouse click at the given (lat,lon)=(48.860,2.340) location
  to viewing the Eiffel Tower with John Bradley's 'xv' program (the |2|
  is there to indicate how accurate the mouse click is supposed to be,
  see below).

Notice that, for instance, the final definition would be equivalent to 
using a command line
-define "exec|2|48.860,2.340|xv eiffel.jpg"

Notice the quotes " " used here to protect special characters | and the
blank space from the shell interpretor. The  character code 31 
(Ctrl-Q Ctrl-_ within 'emacs' or 'emx', and Ctrl-space within xrmap's text
input fields) can (and should) be used to replace blank characters in case 
blank spaces could be interpreted as option separation characters ;
quotes should not be used in those cases.


III. Syntax of the define constructs
------------------------------------

Here is the list of constructs (i.e. concatenated fields separated by
a vertical bar) which can be used as 
  -define "<construct>"
in a command line option. When set in the <defines> section of a rcfile, 
  <construct> 
should appear as it stands starting from the left of the line -- quotes 
"..." should be removed and no blank space is allowed in any of the fields 
( should be used instead).


1)  image|<lat>,<lon>|<name.suf>|height

Draws an image <name.suf> on the map, centered at location
<lat>,<lon>.  Here .suf is any supported image format (currently .xpm, 
.png, .eps, .svg). Files can be gzipped compressed to save space
(except .jpg, .png which are already compressed). If <name.suf> starts
with e.g. $SHAREDIR/picons, xrmap will append the sharedir picons directory,
as set when xrmap was compiled and installed. If the name starts with
$HOME/ or ~/ , xrmap will append the user's home directory. Otherwise, 
the path is understood as a normal absolute or relative path, depending on
the current working directory. The final parameter rescales the image
so that it has given height (final |height is equivalent to height=0,
meaning that the image is not rescaled).

2) color|<name>

Sets the named color as the color to be used for drawing user
defined features. Default is black (check the system wide 'rgb.txt' file
for the list of valid color names).

3) font|<index>

Sets the font of index <index> for user defined text labels. The index
should be 0,1,2,3,4,5 and refers to the font numbering used in
connection with menus and or location labels.

4) label|<pos>|<lat>,<lon>|<string>

Puts a text label <string> at location <lat>,<lon> justified according
to mode <pos>, where <pos> is an integer=0,1...7
         7---6---5
         0       4
         1---2---3
The number indicates where will be the geographic point, if the rectangle
indicates the label. <string> should be an alphanumeric string of
characters, where \n indicates a new line and  (char 31) a blank space.

5) ellipse|<axis_x>,<axis_y>|<lat>,<lon>

Draws an ellipse of main axes <axis_x>,<axis_y> (half-axes, that is),
at location <lat>,<lon>

6) polyline|<lat1>,<lon1>|<lat2>,<lon2>|<lat3>,<lon3>...

Draws a polygonal line passing through the vertices
<lat1>,<lon1>|<lat2>,<lon2>|<lat3>,<lon3>...
The number of points is a priori unlimited

7) polygon|<lat1>,<lon1>|<lat2>,<lon2>|<lat3>,<lon3>...

Draws a *closed* polygonal line passing through the vertices
<lat1>,<lon1>|<lat2>,<lon2>|<lat3>,<lon3>...
The number of points is a priori unlimited. 

8) region|<lat1>,<lon1>|<lat2>,<lon2>|<lat3>,<lon3>...

Draws a filled polygonal region, bounded by a polygonal line passing 
through the vertices
<lat1>,<lon1>|<lat2>,<lon2>|<lat3>,<lon3>...
The number of points is a priori unlimited.

Note: When editing under the map editing menu, putting 'polygon|*',
'polyline|*', 'region|*' is equivalent to listing all points that have
been clicked on.

9) input|<lat1>,<lon1>|<lat2>,<lon2>|<lat3>,<lon3>...
Under the map editing mode, this has the effect of entering the specified
points by the command line. Has no effect on the map itself, but the points
are copied to memory and available for further use.

10) erase|0,3,8...
Under the map editing mode, this erases the points whose indices have been
specified. A single "erase" command without parameter means erasing the 
marked point, if any.

11) eraseall
Under the map editing mode, this erases all shown points.

12) modif|<mode>|<location>

Modifies the label of a given location according to mode <mode>.
<mode> is a 1,2 or 3 field specification which should conform to one of the 
following mutually exclusive possibilities: 
  hide            (never show the label)
  show            (always show the label)
  move|<dx>,<dy>  (move the label by <dx> to the right and by <dy> upwards)
  position|<pos>  (change position style pos=0,1...7 -- as above)

13) exec|<accuracy>|<lat>,<lon>|<system_call>

Creates a system call link at position <lat>,<lon>. When clicking with
left mouse button at <lat>,<lon> up to accuracy <accuracy>, the
specified <system_call> is activated. However, if option +secure is set,
all system calls are disabled. The <accuracy> value should be in the
range 0,1...9, with 2 being standard accuracy (0 means smaller allowed
error, 9 means larger).

14) undef|<rank>

Undefine the define construct of rank <rank>. Putting -define undef|<rank> 
is equivalent to setting
  -undef(ine) <rank>
with the command line.

15) *
A single asterisk in the command line has the effect of opening an editor 
session containing the list of points that are presented in the map 
edition menu. Just a commodity to convert the points that have been
selected with the mouse into something that can be edited as a text file.

Further Note
------------

The text input line has a Copy/Paste buffer that works as usual with
the middle mouse button. When clicking on a point in map edition mode,
the coordinates of the points (with 6 digit accuracy) are copies to
the X primary selection buffer (the "Copy/Paste" buffer)