From 9e06727ecbafd53cd4e7f5e303aa5301c9174194 Mon Sep 17 00:00:00 2001
From: Mike C <mcrosson_git at nusku dot net>
Date: Fri, 20 Jan 2017 12:38:42 -0500
Subject: [PATCH] Update docs to be more useful

---
 README.md            | 54 +++++++++++++++++++++++++-------------------
 manual_processing.md | 25 ++++++++++++++++++++
 2 files changed, 56 insertions(+), 23 deletions(-)
 create mode 100644 manual_processing.md

diff --git a/README.md b/README.md
index 8a15cde..ad42163 100644
--- a/README.md
+++ b/README.md
@@ -1,31 +1,39 @@
 Overview
 =
-This project contains useful info/tools for processing OSM maps into the mapwriter file format (.map)
+This project contains useful info/tools for processing OSM maps into the mapwriter file format (.map). It was developed to help generating offline map files for Locus on Android.
 
-Manual Procedure
+Dependencies / Prereqs
 =
+To run this program you'll need the following
 
-Prep 
-== 
-- Download updated maps: http://download.geofabrik.de/north-america.html and http://download.geofabrik.de/north-america/canada.html  
-- Pull latest osmosis from http://wiki.openstreetmap.org/wiki/Osmosis 
-- Pull latest mapsforge for osmosis from https://github.com/mapsforge/mapsforge/blob/master/docs/Downloads.md 
- 
-Process maps for device 
-== 
-- Setup osmosis in a directory (unzip release -- ZIPBOMB ALERT!!!!) 
-- Create plugins directory under osmosis 
-- Move mapsforge release jar to osmosis/lib/default/ 
-- Decompress maps (if they were previously compressed) 
-- ./osmosis bin/osmosis --rb file=../maps/a_map.osm.pbf --mapfile-writer file=../maps/a_map.map 
--* If you run out of heap space add JAVACMD_OPTIONS="-Xmx16g" to the start of the line 
--* If increasing the heap doesn't work, append type=hd to end of command 
--* You can merge maps using --merge passed to osmosis (before --mapfile-writer) using n-1 instances of --merge where n is the number of --rb or --rx options passed 
- 
-General Notes 
-= 
-Used to generate above info 
-* https://github.com/mapsforge/mapsforge/blob/master/docs/Getting-Started-Map-Writer.md
+* A Linux environment
+* Python 3.x installed
+* Java 1.8 or higher installed (OpenJDK works)
+* wget installed
+* bunzip2 installed (usually part of bzip2 package)
+
+Installation
+=
+Head over to releases tab and download the latest. Extract the file and you're good to go. Everything is self-contained minuse the above dependencies.
+
+Running
+=
+To run the program, cd to the directory where you extracted the release and run './process_maps.py' with at least one '--map-list /path/to/list.txt parameter'. See the lists directory for examples on how to format the map list files.
+
+Program Usage
+=
+usage: process_maps.py [-h] [--map-list MAP_LIST] [--no-sleep] [--use-ram]
+
+optional arguments:
+  -h, --help           show this help message and exit
+  --map-list MAP_LIST  a text file with one map URL per line, can be specified
+                       more than once
+  --no-sleep           don't sleep between downloads -- WARNING you can easily
+                       run into throttling on mirrors if you use this option
+  --use-ram            use RAM for mapsforge processing -- WARNING mapsforge
+                       uses 10x the map size in RAM for processing (ie. 100Mb
+                       map = 1Gb RAM usage), you want a LOT of RAM for this
+                       option
 
 Licencing
 =
diff --git a/manual_processing.md b/manual_processing.md
new file mode 100644
index 0000000..4da6b7d
--- /dev/null
+++ b/manual_processing.md
@@ -0,0 +1,25 @@
+Manual Procedure
+=
+
+Prep 
+== 
+- Download updated maps: http://download.geofabrik.de/north-america.html and http://download.geofabrik.de/north-america/canada.html  
+- Pull latest osmosis from http://wiki.openstreetmap.org/wiki/Osmosis 
+- Pull latest mapsforge for osmosis from https://github.com/mapsforge/mapsforge/blob/master/docs/Downloads.md 
+ 
+Process maps for device 
+== 
+- Setup osmosis in a directory (unzip release -- ZIPBOMB ALERT!!!!) 
+- Create plugins directory under osmosis 
+- Move mapsforge release jar to osmosis/lib/default/ 
+- Decompress maps (if they were previously compressed) 
+- ./osmosis bin/osmosis --rb file=../maps/a_map.osm.pbf --mapfile-writer file=../maps/a_map.map 
+  * If you run out of heap space add JAVACMD_OPTIONS="-Xmx16g" to the start of the line 
+  * If increasing the heap doesn't work, append type=hd to end of command 
+  * You can merge maps using --merge passed to osmosis (before --mapfile-writer) using n-1 instances of --merge where n is the number of --rb or --rx options passed 
+ 
+General Notes 
+= 
+Used to generate above info 
+* https://github.com/mapsforge/mapsforge/blob/master/docs/Getting-Started-Map-Writer.md
+