README

   1                                 osm-helpers
   2         Tools to help the maintenance of the OpenStreetMap database
   3
   4 The tools included here mainly help to check that the data in the
   5 OpenStreetMap database complies with a set of rules and create a description
   6 of the proposed changes and upload them to the database.
   7
   8 See the file MIT.X11 for the license details.
   9
  10 To build issue the commands:
  11         make PREFIX=/usr/local
  12         make PREFIX=/usr/local install
  13
  14 On Debian systems you will need the following packages:
  15         mono-gmcs
  16         mono-cil
  17         mono-runtime
  18         libmono-system-web2.0-cil
  19
  20 * osm-check
  21
  22 osm-check can load osm data from a file on disk or directly from
  23 the OpenStreetMap database given a latitude/longitude pair.
  24 The loaded data is checked against a few compliance rules:
  25         *) no extra whitespace in the middle, the start or the end
  26         of tag values
  27         *) abbreviations at the start of tag values are expanded
  28         *) uniform case of the first word in tag values
  29
  30 The suggested changes to the data are output to stdout or to a file
  31 in an XML format. This file can be inspected for mistakes and then fed to
  32 osm-upload-changes to upload to the OpenStreetMap database server.
  33 Other rules will be added in the next releases.
  34
  35 The rules are described in an XML file, loaded from
  36 $HOME/.config/osm-helpers/osm-check.rules by default (use the --rules
  37 option to specify a different file).
  38
  39 Each abbreviation is specified with the following element:
  40         <abbr from="abbr." to="Abbreviation" />
  41 where each "abbr." at the start of a tag value is expanded to
  42 "Abbreviation".
  43 See it.osmrules for examples.
  44
  45 The street type names at the start of a tag value are instead specified
  46 with the element:
  47         <way name="Street" />
  48
  49 Tags or tag-value combinations that are inappropriate for some object types
  50 can be removed with entries like the following:
  51         <remove type="node" tag="highway" val="secondary" />
  52
  53 * osm-upload-changes
  54
  55 osm-upload-changes takes a file generated by osm-check and uploads the
  56 individual changes one by one, avoiding the overwriting of data as much
  57 as possible (the race window is under one second vs the minutes or hours
  58 when using some other mass-update scripts). This also means that
  59 the uploading process can be somewhat slow (depending mostly on the
  60 performance of the OpenStreetMap server).
  61 A username and password are required to upload the changes: currently they
  62 are read from the file $HOME/.config/osm-helpers/osm-auth, which
  63 contains the username in the first line and the password in the second
  64 or, if that file is not present they can be entered at the console
  65 prompt.
  66
  67 osm-upload-changes prints a dot for each successful upload, an asterisk
  68 for a change skipped because it's no longer valid, a letter if something
  69 failed in the download or in the upload of the data. A sumamry is printed
  70 as well at the end of the process.
  71 The --no-upload option can be used to do everything except the actual
  72 database upload.
  73
  74 Notifications of the changes made to database objects can be sent to the
  75 contributor that last changed the object at osm-check time using the --notify option.
  76 A default message is sent with a detailed list of the changes made. If you want to
  77 use a different message, specify a template file to use with the option:
  78         --notify=template_file
  79
  80 The content of the file will be sent as the message, with the following changes:
  81         @USER@ is changed to the name of the user receiving the message
  82         @CHANGES@ is replaced with the list of changes
  83
  84 See the template file for an example.
  85
  86 * osm-changes file format
  87
  88 The changes are described in an XML file with the following structure:
  89
  90 a toplevel element (osmchanges) that contains a list of node, way or
  91 relation elements. Each of these elements must contain an id attribute
  92 (whis is the OpenStreetMap id), a tag attribute with the name of the tag
  93 to change, an old attribute with the value that should be changed and a new
  94 attribute with the new value for the tag. If at the time of the upload
  95 the tag value in the database doesn't match the old value, the update is
  96 skipped. There is also a user attribute: this was the user that last changed
  97 the object at the time the object was checked with osm-check.
  98
  99 * osm-history
 100
 101 osm-history can be used to download the history of an object in the osm db
 102 and have a summary of the differences between each revision.
 103