Preliminary user howto
~~~~~~~~~~~~~~~~~~~~~~

0. temporary hacks

The project is in alpha testing phase. Expect (and report) random bugs.
Sharp corners everywhere.

Please check INSTALL in the root of the project for dependencies.

Editing or displaying relations is not yet supported.


1. Startup, getting data

Compiling: please read the file INSTALL.

Normal startup is without arguments. The empty database shown is a small
area around the "home" location, which is configurable in lat/lon
(which are always decimal degrees, e.g. 19.1234567) in rc/home/lat and
rc/home/lon. These will be considered only during startup so if you change
them make sure to do it on user role or higher and then restart osm-rnd.

Use the ':' key to get a command prompt. Commands to get data:
  - Update - without arguments it downloads osm map data (vector data)
    around the area currently visible in the window (can be smaller or
    larger than the initial empty black data)
  - shorthand to Update is "up"
  - Update(gpx) - downloads the latest 5000 gpx tracks for the currently
    visible area
  - bing - displays the Bing aerial/sat layer on the bottom; this is legal
    to use for osm mapping, with attribution (automatic in changeset tags)

Note: for the Update() action, if your area is too small, you may get an
      empty download, or if it is too large the server may refuse the
      request. You can see the resutl of wget in the message log and/or on
      stderr.

Zoom and pan around; as long as the osm layer is selected a subsequent
update() will extend the data in that layer so you can download a bigger,
non-rectangular area in smaller portions.

Note: the API Update() uses is excusively for editing. For viewing-only there
      will be a different method of getting data.

2. Authentication

Read-only access is anonymous. If you plan to commit, you need to set up
a password file:

  mkdir ~/.osm-rnd
  touch ~/.osm-rnd/basic_auth
  chmod 600 ~/.osm-rnd/basic_auth

Then edit ~/.osm-rnd/basic_auth adding two lines:

  user=your_osm_username_here
  password=your_osm_password_here

At the moment oath is not supported, you need to have an user+pass and the
basic http user auth is used (through https).

3. editing

Make sure the osm data layer is selected. The cursor and tools are going to
be reacting only on objects on the current layer.

You probably want to enable the wireframe mode (hotkey: |)

Use the node tool to place nodes. If placed over a way, the node is automatically
inserted into the existin way. If placed over a crossing of multiple ways,
the new node is inserted in all ways as a common node. use right click over
the node to get a context menu for editing tags.

Use the way tool to draw a multi-segment way - automatically places nodes
(the same as above). The operation ends if:
 - the loop is closed, returning to the starting node of the way
 - ESC is pressed
 - upon right click

Editing or displaying relations is not yet supported.

For more advanced editing tips see howto_edit.txt

4. commiting

Use the Commit action from the command line (or the shorthand ci).
It prints a summary of the local differences you
are going to commit; #number means object ID, negative ID means new object
created locally. A commit dialog is also popped up. If you find the summary
sound, enter a comment, revise automatically generated changeset tags, maybe
add more tags. If the dialog is closed or cancelled, no communication to the
server is made and all local changes are kept as-is. If the commit is
started, a changeset is generated, all changes uploaded as a transaction and
the changeset is closed.

If the commit fails, an error message appears in the message log. Upon
a succesful commit all local changes are on the server so the undo list
is cleared and the in-memory layer has no local change.


5. Imagery layer alignment

Select the imagery layer (e.g. Bing), click the ALIG tool in the toolbar, grab
the image and perform a drag&drop. The new offset is set in the config. The
config location depends on the plugin serving the layer, for bing it's
plugins/img_bing/offs/x and plugins/img_bing/offs/y. Offsets are
specified in meter and are applied onto the 2d projection right before rendering.