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 do the
oauth2 rain dance:

First make sure you have an ~/.osm-rnd:

  mkdir ~/.osm-rnd

Then start a commit, fill in the commit message and click on the "Commit!"
button. Since you do not yet have an "access token", osm-rnd will pop up
a dialog that gives you an URL. Open a web2.0 browser and type in that
URL. It will present you a page with a few links; click on the one for
your use case.

This will redirect you to the official OpenStreetMap login. After logging in,
you get a page that asks whether you want to grant permissions to osm-rnd for
the given operations. Verify it's for osm-rnd, verify the permissions and
if everything looks good, click Authorize.

This will give you a page with an Authorization Code, a long text of ASCII
letters, digits and dashes and underscores. Copy this back into the dialog box
that gave you the URL and click OK.

Now osm-rnd goes and does two more https steps to get an "access token". It
will announce the outcome in the message log. When it worked, it saves
the auth code and access token in ~/.osm-rnd and will reuse the access token
in subsequent commits so the whole process of using a web2.0 browser and
copying auth codes won't need to be repeated.

If authentication breaks any time, just remove ~/.osm-rnd/oauth2* and the
whole process is repeated from scratch.


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.