Improve documentation

* Improve documentation about BRouter usage and the provided scripts
(misc/scripts).
* Document how to use BRouter with third-party apps on Android (Locus /
OSMAnd).
* Improved process_planet_pbf.sh map creation script to make use of
osmupdate if available and avoid downloading the planet file if not
needed.

misc/readmes/mapcreation.md

@@ -0,0 +1,81 @@
+Build your own BRouter segments files
+=====================================
+
+BRouter uses its own data format (`.rd5` files), split in tiles of 5 x 5
+in latitude and longitude. You can download the official segment files (weekly
+built) from [brouter.de](http://brouter.de/brouter/segments4/) but you can
+also build them yourself from an OSM dump.
+
+
+## Build the pbfparser
+
+First, there are two file formats available to download OSM data: `bzip`-ed
+XML files (very large) and `.pbf`
+([Protobuf](https://github.com/protocolbuffers/protobuf) format) which is much
+more efficient. If you want to use the latter one, you will have to build the
+`pbfparser` (located in `misc/pbfparser` first):
+
+* Download [the latest
+    version](https://bretth.dev.openstreetmap.org/osmosis-build/osmosis-latest.zip)
+    of [Osmosis](https://wiki.openstreetmap.org/wiki/Osmosis) and unzip it
+    somewhere.
+* Copy the `lib/default/protobuf-java-*.jar` and
+    `lib/default/osmosis-osm-binary-*.jar` files from the unzipped Osmosis
+    archive to `misc/pbfparser/protobuf.jar` and `misc/pbfparser/osmosis.jar`.
+* Build BRouter and copy
+    `brouter-server/target/brouter-server-*-jar-with-dependencies.jar` to
+    `misc/pbfparser/brouter.jar`.
+* You can build the `pbfparser` using, in the `misc/pbfparser/`
+    folder,
+
+```
+javac -d . -cp "brouter.jar:protobuf.jar:osmosis.jar" *.java
+```
+
+* Finally, you can build a `jar` file from these files using
+
+```
+jar cf pbfparser.jar btools/**/*.class
+```
+
+_Note:_ If the `jar` file is not properly created, everything else will seem
+to work normally but there will not be any data extracted from the OSM data
+dump. You can check what is actually inside the built `jar` file using
+`jar tf pbfparser.jar`.
+
+
+## Run the map creation script
+
+If you want to have elevation information in the generated segments files, you
+should download the required [SRTM
+files](https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/)
+and set the `SRTM_PATH` variable when running the `process_pbf_planet.sh`
+script.
+
+Any flavor of the 90m SRTM database should be working, but the one used by the
+official BRouter segments files are the ones provided by
+[CGIAR](https://cgiarcsi.community/data/srtm-90m-digital-elevation-database-v4-1/).
+If you are working with rather small geographical extracts, you can download
+tiles manually using [this
+interface](http://srtm.csi.cgiar.org/SELECTION/inputCoord.asp) (use the
+"ArcInfo ASCII" format), instead of having to ask for an access for bulk
+download of data. There is no need to unzip the downloaded files, the
+`process_pbf_planet.sh` script expects a folder with all the ZIP files inside
+and will manage it.
+
+Note that if you don't have the SRTM data available, the segments files will
+still be generated without any issue (but they will miss the elevation data).
+If you are not sure which SRTM files you have to download, you can run the
+script once and it will log all the SRTM files it is looking for.
+
+You can now run the `misc/scripts/mapcreation/process_pbf_planet.sh` script to
+build the segments. Have a look at the variables defined at the beginning of
+the files and overwrite them according to your needs. By default, the script
+will download the latest full planet dump from
+[planet.osm.org](https://planet.osm.org/). You can also download a
+geographical extract provided by [Geofabrik](https://download.geofabrik.de/)
+and set the `PLANET_FILE` variable to point to it.
+
+_Note:_ It is possible that you encounter an error complaining about not being
+able to run `bash^M` on Linux/Mac OS. You can fix this one by running
+`sed -i -e 's/\r$//' process_pbf_planet.sh`.

misc/readmes/osmand/README.md

@@ -0,0 +1,64 @@
+Using BRouter on Android with OSMAnd
+====================================
+
+BRouter integration in OSMAnd changed a lot during the summer of 2019. This
+guide assumes you are using the BRouter Android app in version 1.5.0 or higher
+as well as OSMAnd in version 3.4 or higher.
+
+
+## Installing BRouter app on your Android device
+
+First, install the BRouter app on your Android device from
+[F-Droid](https://f-droid.org/packages/btools.routingapp) or [Google Play
+Store](https://play.google.com/store/apps/details?id=btools.routingapp). You
+can also build the BRouter Android app yourself.
+
+<a href="https://f-droid.org/packages/btools.routingapp" target="_blank">
+<img src="https://f-droid.org/badge/get-it-on.png" alt="Get it on F-Droid" height="90"/></a>
+<a href="https://play.google.com/store/apps/details?id=btools.routingapp" target="_blank">
+<img src="https://play.google.com/intl/en_us/badges/images/generic/en-play-badge.png" alt="Get it on Google Play" height="90"/></a>
+
+
+## Downloading BRouter segments
+
+Then, launch the BRouter app and choose "Download Manager". Zoom in and select
+the areas you want to route in. Then click "Start Download" and BRouter will
+start downloading the [segments](http://brouter.de/brouter/segments4/) files
+for the selected areas.
+
+<img src="./brouter-main.png" alt="Main menu of BRouter android app"/>
+
+<img src="./brouter-grid.png" alt="Grid selection of segments to download"/>
+
+Note that you will have to repeat this step periodically, whenever you want to have an
+updated version of the OSM data used for the routing.
+
+
+## Selecting profiles to use
+
+Once this is done, start again the BRouter app and choose the "BRouter App"
+entry on the main menu. Select the routing profile you want to use and click
+"Server-Mode". Then, tick the boxes for the routing modes you want to use this
+profile for. You can use two different profiles per transportation mode, which
+will be mapped to the "shortest" and "fastest" presets (these are just
+labelling) in OSMAnd.
+
+<img src="./brouter-profiles.png" alt="Profiles selection"/>
+
+<img src="./brouter-profiles-summary.png" alt="Profiles selection summary"/>
+
+
+## Configure OSMAnd to make use of BRouter offline navigation
+
+You can now create an "Application profile" in OSMAnd which will be using
+BRouter for offline routing. Go to Settings -> Application profiles -> Add and
+create a new profile based on the base profile of your choice (cycling here,
+for bicycle routing), with a custom name of your choice ("BRouter" on the
+screenshot below) and making use of "BRouter (offline)" for navigation.
+
+<img src="./brouter-osmand.png" alt="BRouter configuration in OSMAnd
+application profiles"/>
+
+The BRouter app should be launched before OSMAnd for this specific entry to
+appear in OSMAnd. Therefore, if you cannot find "BRouter (offline)" navigation
+option, you should force quit OSMAnd and restart it.