imported AsciiDoctor documentation into the project,

better documentation integration into the site navigation

documentation/Makefile

@@ -0,0 +1,22 @@
+stylesheet = rocket-panda.css
+styledir   = /usr/local/share/asciidoctor/stylesheets
+remote     = h4:/home/maposmatic/maposmatic/www/static/documentation
+
+all: html pdf
+
+html: api-docs.html user-guide.html
+pdf: api-docs.pdf user-guide.pdf
+
+%.html: %.txt
+	asciidoctor $<
+
+%.pdf: %.txt 
+	asciidoctor-pdf $<
+
+clean:
+	rm -f *.html *.pdf *~
+
+install: all
+	cp *.html ../www/maposmatic/templates
+
+.PHONY = html clean all install

documentation/api-docs.txt

@@ -0,0 +1,469 @@
+MapOSMatic remote rendering API
+===============================
+Hartmut Holzgraefe <hartmut@php.net>
+:toc:
+:toclevels: 2
+:source-highlighter: coderay
+:data-uri:
+:numbered:
+v1, September 16th 2018 (Work in progress)
+
+MapOSMatic is a web frontend for the OCitySMap renderer, which uses
+the Mapnik map rendering libary, Python and the CairoGraphics library
+to create decorated single page maps and multi page atlas-like booklets.
+
+Originally this was a pure user centric web GUI, but recently a wish
+for using the infrastructure with different web frontends did come up.
+
+So this HTTP API provides an alternative way to submit map rendering
+requests, and to retrieve additional data that may be needed on the
+way.
+
+Requests and results are submitted as JSON documents, with the
+optional possibility to attach extra data files, like GPX tracks
+or Umap user created maps.
+
+This documentation begins with describing the helper calls that
+provide lists of possible choices for different data fields,
+followed by the actual map rendering call and how to retrieve
+rendering status and results, and ends with example programs
+to access the API from different programming languages.
+
+API calls
+---------
+
+Paper Formats
+~~~~~~~~~~~~~
+
+Request URL
+^^^^^^^^^^^
+
+----
+https://api.get-map.org/apis/paper_formats
+----
+
+Example result
+^^^^^^^^^^^^^^
+
+----
+{
+    "Best fit": {
+        "height": null,
+        "width": null
+    },
+    "Din A4": {
+        "height": 297,
+        "width": 210
+    },
+    "US letter": {
+        "height": 279,
+        "width": 216
+    }
+}
+----
+
+
+
+
+Layouts
+~~~~~~~
+
+Request URL
+^^^^^^^^^^^
+
+----
+https://api.get-map.org/apis/layouts
+----
+
+Example result
+^^^^^^^^^^^^^^
+
+----
+{
+    "multi_page": {
+        "description": "A multi-page layout.",
+        "preview_url": "https://api.get-map.org/media/img/layout/multi_page.png"
+    },
+    "plain": {
+        "description": "Full-page layout without index.",
+        "preview_url": "https://api.get-map.org/media/img/layout/plain.png"
+    },
+    "single_page_index_bottom": {
+        "description": "Full-page layout with the index at the bottom.",
+        "preview_url": "https://api.get-map.org/media/img/layout/single_page_index_bottom.png"
+    },
+    "single_page_index_side": {
+        "description": "Full-page layout with the index on the side.",
+        "preview_url": "https://api.get-map.org/media/img/layout/single_page_index_side.png"
+    }
+}
+----
+
+
+
+Base Styles
+~~~~~~~~~~~
+
+Request URL
+^^^^^^^^^^^
+
+----
+https://api.get-map.org/apis/styles
+----
+
+Example output
+^^^^^^^^^^^^^^
+
+----
+{
+    "CartoOSM": {
+        "annotation": "OpenStreetMap Carto standard style",
+        "description": "CartoCSS OSM standard style",
+        "preview_url": "https://api.get-map.org/media/img/style/CartoOSM.png"
+    },
+    "GermanCartoOSM": {
+        "annotation": "German OSM style based on OSM Carto",
+        "description": "German OSM style",
+        "preview_url": "https://api.get-map.org/media/img/style/GermanCartoOSM.png"
+    }
+}
+----
+
+
+Overlay Styles
+~~~~~~~~~~~~~~
+
+Request URL
+^^^^^^^^^^^
+
+----
+https://api.get-map.org/apis/overlays
+----
+
+
+Example output
+^^^^^^^^^^^^^^
+
+----
+{
+    "OpenRailwayMap_Overlay": {
+        "annotation": "OpenRailwayMap overlay",
+        "description": "OpenRailwayMap rail line overlay",
+        "preview_url": "https://api.get-map.org/media/img/style/OpenRailwayMap_Overlay.jpg"
+    },
+    "Scale_Bar_overlay": {
+        "annotation": "",
+        "description": "Map scale bar"
+        "preview_url": "https://api.get-map.org/media/img/style/Scale_Bar_overlay.jpg"
+    }
+ }
+----
+
+
+Job Stati
+~~~~~~~~~
+
+Request URL
+^^^^^^^^^^^
+
+----
+https://api.get-map.org/apis/job_stati/
+----
+
+Example result
+^^^^^^^^^^^^^^
+
+----
+{
+    "0": "Submitted",
+    "1": "In progress",
+    "2": "Done",
+    "3": "Done w/o files",
+    "4": "Cancelled"
+}
+----
+
+
+Submitting a Job
+~~~~~~~~~~~~~~~~
+
+Request URL
+^^^^^^^^^^^
+
+----
+POST https://api.get-map.org/apis/jobs/
+----
+
+
+Expects render job named parameters as a JSON collection.
+
+Possible parameters:
+
+osmid:: ID of an object in the osm2pgsql
+bbox_top:: 
+bbox_bottom:: 
+bbox_left:: 
+bbox_right:: Render area min. bounding box, may be extended to fit paper format
+title:: Text to put into the title box (default: "Untitled API Request")
+language:: locale to use for rendering (default: "en_US.UTF-8")
+layout:: Map layout to use (default: "plain")
+style:: Map base style to use (default: "CartoOSM")
+overlays:: List of overlays to put on top of base style (default: None)
+paper_size:: Paper size to use (default: "Din A4" 210x297mm²)
+orientation:: Paper orientation: "portrait" or "landscape" (default: "portrait")
+track_url:: URL pointing to a GPX track to download and print
+umap_url:: URL pointing to an Umap export file do download and print
+
+It is also possible to upload GPX and Umap files directly using a multipart/form-data
+POST request. In this case you have to submit the actual API JSON as a post parameter
+named "json", and add file fields named "track" for a GPX track, or "umap" for an
+Umap JSON export.
+
+After successfully submitting a request you can either poll the job result API every
+once in a while until it either returns the "200 OK" status, or a 4xx error code.
+Or you can redirect a web client to the human readable result page listed in the
+returned "interactive" job parameter.
+
+Return codes
+^^^^^^^^^^^^
+
+202:: 'Accepted' when successfully submitted, "Location:" header will contain result URL
+400:: 'Bad request' on request validation errors
+
+Example requests
+^^^^^^^^^^^^^^^^
+
+----
+Content-type: application/json
+
+{
+    "title": "API Test",
+    "bbox_bottom": 52.00,
+    "bbox_left": 8.52,
+    "bbox_right": 8.50,
+    "bbox_top": 52.02
+}
+----
+
+----
+Content-Type: multipart/form-data; boundary=--XXXXXXXX
+
+--XXXXXXXX
+Content-Disposition: form-data; name="json"
+
+{
+    "title": "GPX Test",
+    "paper_size": "Din A1"
+}
+--XXXXXXXX
+Content-Disposition: form-data; name="track"; filename="test.gpx"
+Content-Type: application/gpx+xml
+
+<?xml version="1.0" encoding="UTF-8"?>
+  
+<gpx version="1.1">
+  <metadata>
+    <name>GPX test</name>
+  </metadata>
+  <trk>
+    <trkseg>
+      <trkpt lat="52.00" lon="8.50" />
+      <trkpt lat="52.02" lon="8.52" />
+    </trkseg>
+  </trk>
+</gpx>
+--XXXXXXXX--
+----
+
+Example results
+^^^^^^^^^^^^^^^
+
+----
+HTTP/1.1 202 Accepted
+[...]
+Location: /api/jobs/36
+Content-Type: text/json
+
+{
+    "bbox_bottom": 52.01,
+    "bbox_left": 8.52,
+    "bbox_right": 8.50,
+    "bbox_top": 52.02,
+    "id": 36,
+    "interactive": "https://api.get-map.org/maps/214"
+    "language": "en_US.UTF-8",
+    "layout": "plain",
+    "paper_height_mm": 297,
+    "paper_width_mm": 210,
+    "status": 0,
+    "styles": "CartoOSM"
+    "title": "API Test",
+}
+----
+
+----
+HTTP/1.1 400 Bad Request
+[...]
+Content-Type: text/json
+ 
+{
+    "error": {
+        "non_field_errors": [
+            "No bounding box area or OsmID given"
+        ]
+    }
+}
+----
+
+
+Checking Job results
+~~~~~~~~~~~~~~~~~~~~
+
+Request Url
+^^^^^^^^^^^
+
+----
+https://api.get-map.org/apis/jobs/
+----
+
+Return codes
+^^^^^^^^^^^^
+
+200:: 'OK' when request has been processed successfully
+202:: 'Accepted' when rendering is still in progress, "Location:" header will contain same URL again
+410:: 'Gone' when a request had been processed successfuly in the past, but result files have since been purged to free file system space
+400:: 'Bad request' when a request failed to render
+
+Example result
+^^^^^^^^^^^^^^
+
+----
+HTTP/1.1 200 OK
+[...]
+Content-type: application/json
+
+{
+    "bbox_bottom": 52.01,
+    "bbox_left": 8.53,
+    "bbox_right": 8.49,
+    "bbox_top": 52.02,
+    "files": 
+    {
+        "8bit.png": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.8bit.png",
+        "jpg": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.jpg",
+        "pdf": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.pdf",
+        "png": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.png",
+        "svgz": "https://api.get-map.org/results//000215_2018-09-12_23-14_GPX-test.svgz"
+    }
+    "id": 215,
+    "language": "en_US.UTF-8",
+    "layout": "plain",
+    "paper_height_mm": 594,
+    "paper_width_mm": 841,
+    "queue_size": 0,
+    "status": 2,
+    "style": "CartoOSM",
+    "title": "GPX test"
+}
+----
+
+
+
+Example code
+------------
+
+
+PHP
+~~~
+
+All examples in this script use the `PEAR:HTTP_Request2` class for sending
+HTTP requests and receiving server replies. 
+
+Retrieve parameter choices
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Here we are using the `/paper_formats`, `/layouts`, `styles` and `overlays`
+API calls to retrieve possible choices for all of these parameters, and
+their textual description where available.
+
+.parameters.php
+[source,php]
+----
+include::code-snippets/parameters.php[]
+----
+
+
+Submitting a simple request
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Now we are submitting a simple request, only setting the map title,
+and the bounding box of the area to display. We do not check for
+rendering to complete, but redirect the web client to the interactive
+result URL given as `interactive` in the returned JSON data.
+
+This is the same result page as when you submit a map request manually
+via the standard web user interface, so this approach is suitable for
+interactive web applications:
+
+.simple-request.php
+[source,php]
+----
+include::code-snippets/simple-request.php[]
+----
+
+
+Attaching a file
+^^^^^^^^^^^^^^^^
+
+Now, to make things more interesting, we are going to attach a GPX
+file to our request. As the page title and the necessariy bounding
+box to fit all track data can be extracted from the file, if it is
+a valid GPX file, we do not need to pass any other data at all.
+
+.file-request.php
+[source,php]
+----
+include::code-snippets/file-request.php[]
+----
+
+
+
+
+Wait for rendering to complete
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To have your application check for the rendering status yourself
+you need to poll the `/jobs` status page, adding the job `id`
+returned by the API. Please wait at least 15 seconds between
+status poll requests.
+
+As long as the returned HTTP status is "202 Accepted" the
+request is either currently being processed, or still
+waiting in the job queue.
+
+When the job has completed successfully "200 OK" will be returned,
+and the `files` object in the returned JSON result will contain
+a hash of produced file formats, and under what URL each of them
+can be retrieved.
+
+In the example we retrieve the PDF version, and start the users
+preferred PDF viewer to present the result.
+
+.wait-for-result.php
+[source,php]
+----
+include::code-snippets/wait-for-result.php[]
+----
+
+
+Python
+~~~~~~
+
+To be done
+
+
+Javascript
+~~~~~~~~~~
+
+To be done, maybe. Due to the "same origin" restrictions
+this is low on my list ...

documentation/code-snippets/file-request.php

@@ -0,0 +1,28 @@
+<?php
+require_once 'HTTP/Request2.php';
+
+define('BASE_URL', 'https://api.get-map.org/apis/v1/');
+define('GPX_FILE', 'A1.gpx');
+
+$data = [];
+
+$request = new HTTP_Request2(BASE_URL . "jobs");
+
+$request->setMethod(HTTP_Request2::METHOD_POST)
+        ->addPostParameter('job', json_encode($data))
+        ->addUpload('track', GPX_FILE, basename(GPX_FILE), 'application/gpx+xml');
+
+$response = $request->send();
+$status   = $response->getStatus();
+
+echo "$status: ".$request->getBody()."\n";
+
+if ($status < 200 || $status > 299) {
+    header("Content-type: text/plain");
+    print_r($response->getBody());
+    exit;
+}
+
+$reply = json_decode($response->getBody());
+
+echo "$status: ".$reply->interactive."\n";

documentation/code-snippets/parameters.php

@@ -0,0 +1,42 @@
+<?php
+require_once 'HTTP/Request2.php';
+
+define('BASE_URL', 'https://api.get-map.org/apis/v1/');
+
+function api_call($url) 
+{
+  $request = new HTTP_Request2(BASE_URL . $url);
+
+  $request->setMethod(HTTP_Request2::METHOD_GET);
+  
+  $response = $request->send();
+  $status = $response->getStatus();
+
+  if ($status < 200 || $status > 299) {
+	  echo "invalid HTTP response to '$url': $status\n";
+	  echo $response->getBody();
+	  exit(3);
+  }
+
+  return json_decode($response->getBody());
+}
+
+echo "PAPER FORMATS:\n";
+$paper_formats = api_call('paper_formats');
+foreach ($paper_formats AS $name => $format) 
+  printf("%-10s: %4dx%4d mm²\n", $name, $format->width, $format->height);
+
+echo "\nLAYOUTS\n";
+$layouts = api_call('layouts');
+foreach ($layouts as $name => $layout) 
+  printf("%-25s: %s\n", $name, $layout->description);
+
+echo "\nSTYLES\n";
+$styles = api_call('styles');
+foreach ($styles as $name => $style) 
+  printf("%-25s: %s\n", $name, $style->description);
+
+echo "\nOVERLAYS\n";
+$overlays = api_call('overlays');
+foreach ($overlays as $name => $overlay) 
+  printf("%-25s: %s\n", $name, $overlay->description);

documentation/code-snippets/simple-request.php

@@ -0,0 +1,30 @@
+<?php
+require_once 'HTTP/Request2.php';
+
+define('BASE_URL', 'https://api.get-map.org/apis/v1/');
+
+$data = ['title'       => 'PHP Test',
+         'bbox_bottom' => 52.00,
+         'bbox_top'    => 52.02,
+         'bbox_left'   => 8.50,
+         'bbox_right'  => 8.52
+        ];
+
+$request = new HTTP_Request2(BASE_URL . "jobs");
+
+$request->setMethod(HTTP_Request2::METHOD_POST)
+		->setHeader('Content-type: application/json; charset=utf-8')
+		->setBody(json_encode($data));
+
+$response = $request->send();
+$status   = $response->getStatus();
+
+if ($status < 200 || $status > 299) {
+    header("Content-type: text/plain");
+    print_r($response->getBody());
+    exit;
+}
+
+$reply = json_decode($response->getBody());
+
+header("Location: " . $reply->interactive);

documentation/code-snippets/wait-for-result.php

@@ -0,0 +1,84 @@
+<?php
+require_once 'HTTP/Request2.php';
+
+define('BASE_URL', 'https://api.get-map.org/apis/v1/');
+
+function api_GET($url) 
+{
+  $request = new HTTP_Request2(BASE_URL . $url);
+
+  $request->setMethod(HTTP_Request2::METHOD_GET);
+  
+  $response = $request->send();
+  $status = $response->getStatus();
+
+  if ($status < 200 || $status > 299) {
+	  echo "invalid HTTP response to '$url': $status\n";
+	  echo $response->getBody();
+	  exit(3);
+  }
+
+  return array($status, json_decode($response->getBody()));
+}
+
+
+$data = ['title'       => 'PHP Test',
+         'bbox_bottom' => 52.00,
+         'bbox_top'    => 52.02,
+         'bbox_left'   => 8.50,
+         'bbox_right'  => 8.52
+        ];
+
+$request = new HTTP_Request2(BASE_URL . "jobs");
+
+$request->setMethod(HTTP_Request2::METHOD_POST)
+		->setHeader('Content-type: application/json; charset=utf-8')
+		->setBody(json_encode($data));
+
+$response = $request->send();
+$status   = $response->getStatus();
+
+if ($status < 200 || $status > 299) {
+    header("Content-type: text/plain");
+    print_r($response->getBody());
+    exit;
+}
+
+$reply = json_decode($response->getBody());
+
+echo $reply->interactive."\n";
+
+$job_url = "/jobs/" .  $reply->id;
+
+    echo "waiting ... ";
+    sleep(15);
+    list($status, $reply) = api_GET($job_url);
+
+    switch ($status) {
+    case 200:
+        $done = 1;
+        break;
+    case 202:
+        switch($reply->status) {
+        case 0:
+            echo "still in queue\n";
+            break;
+        case 1:
+            echo "now being rendered\n";
+            break;
+        default:
+            echo "unexpected status: ".$reply->status."\n";
+            break;
+        }
+        break;
+    default:
+        die("unexpected HTTP status: $status");
+        break;
+    }
+}
+
+$pdf = basename($reply->files->pdf);
+copy($reply->files->pdf, $pdf);
+
+system("xdg-open $pdf");
+rm($pdf);

documentation/user-guide.txt

@@ -0,0 +1,296 @@
+MapOSMatic User Guide
+=====================
+Hartmut Holzgraefe <hartmut@php.net>
+:toc:
+v0.1, May 5th, 2018
+Work in progress
+
+:imagesdir: ./img
+:data-uri:
+:numbered:
+
+Overview
+--------
+
+
+
+Creating a map - step by step
+-----------------------------
+
+The map creation form leads you through a series of steps that each
+cover a specific step in the overal map creation workflow. Which
+step you are in is visualized in an icon bullet bar.
+
+image:step-progress-bar.png[Select City,width=80%,pdfwidth=80%,align=center]
+
+You can only navigate between steps with the [Next] and [Back] buttons
+though, as some steps depend on spefic input from previous steps.
+So it is not possible to navigate between arbitrary steps by clicking
+on the step icons.
+
+The [Next] button will appear whenever a valid choice was made in
+the current step, the [Back] button is visible on all but the first
+step. On the final step a [Generate Map] button is shown instead
+of the [Next] button.
+
+
+Select a map area or upload a file
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+At the very beginning the map area to be rendered needs to be determined.
+For this there are currently four alternatives, available as different
+form tabs:
+
+* Directly select a rectangular area on an online map
+* Use a city or place name to look up its boundaries in the OSM database
+* Upload a GPX track, the map area will be the tracks bounding box
+* Upload an Umap file, the map area will be determined by the contained data
+
+When uploading a file you can still select a different, e.g. smaller or larger,
+map area afterwards.
+
+
+
+Directly Select Area
+^^^^^^^^^^^^^^^^^^^^
+
+image::select-area.png[Select Area,width=80%,pdfwidth=80%,align=center]
+
+Here you can select a rectangular map area. The map shown is a typical “slippy” online map,
+on the left you have buttons for zooming in and out, a button to detect your current location,
+and a search button to search for a place by name.
+
+By default the full visible map area is selected here, but you may also use the *[Select area]*
+button to enable a more sophisticated area selection tool.
+
+When pressing the *[Select area]* button the user interface changes a bit, you'll now see a
+highlighted rectangular area that marks the actual selected area. You can drag the four corners
+of the rectangle around to change its shape and size, and you can move the complete area by
+dragging it along by the dotted marker in its upper left corner.
+
+With *[Select area within current zoom]* you can make the full visible area the new selection,
+and the *[Remove selection]* brings you back to the original mode.
+
+The four number fields below the map show the current min. and max. latitude and longitude
+of your selected area.
+
+When you are satisfied with your selection you can use the *[>]* button on the right to move
+on to the next form step. 
+
+
+
+City Search
+^^^^^^^^^^^
+
+image:select-city.png[Select City,width=80%,pdfwidth=80%,align=center]
+
+On the “City search” tab you can enter a city or place name in the input field, if the administrative
+borders of that city or place are known to OpenStreetMap these can be used to determine the map area
+to use automatically.
+
+A dropdown below the field will show possible matches for your input as you type. Only the matches
+that are printed in black are selectable. The matches printed in grey are either place nodes for
+which no border information is available in OSM yet, or the place area is too large to be printed
+with this web service. 
+
+
+Upload a GPX Track
+^^^^^^^^^^^^^^^^^^
+
+image::select-gpx.png[GPX Upload,width=80%,pdfwidth=80%,align=center]
+
+Here you can upload a GPX file containing GPS data and waypoints. The track, and all
+named waypoints, will then be rendered on top of the base map.
+
+For now you can only select a single GPX file, support for multiple track files may
+be added in the future.
+
+The upload form performs some basic checks, so it will complain when the uploaded
+file is not in GPX format, or does not contain any usable tracks.
+
+Note that the file will be stored on the web server, and that the map generated from
+it (but not the actual GPX file) will be visible to everyone. So do not upload any
+sensitive data you don't want to to be seen in public, or that you don't have the
+permission for to share it in public.
+
+
+image::gpx-selected.png[GPX Preview,width=80%,pdfwidth=80%,align=center]
+
+Once a valid GPX file has been selected the form switches back to the area selection
+tab, and will show a preview of the file contents and the optimal map area to display
+all contained GPS data.
+
+If you want to render a different area, e.g. just a smaller part of the track, or a
+larger area showing more context beyond the track area itself, you can change the
+selection area accordingly.
+
+
+image::gpx-result.png[GPX Render Result,width=80%,pdfwidth=80%,align=center]
+
+The actual final result of a rendered GPX track may look like the example to the left. 
+
+
+
+Upload a Umap File
+^^^^^^^^^^^^^^^^^^
+
+Here you can upload a file exported from Umap, a service that lets you create online
+maps with your own markers and drawings on top. We provide you with a way to also use
+this fine tool to produce customized printed maps with your own data on top, and not
+only online maps.
+
+To create an export file from a Umap you created you need to click on the
+“Embed and Share” Icon on the left side of the Umap interface, and then use
+“Download Data → Full map data” in the sidebar on the right hand size.
+
+The upload form performs some basic checks, so it will complain when the uploaded file
+is not in Umap format, or does not contain any usable data.
+
+Only data directly added using the Umap drawing tools will be rendered for now.
+Umap also allows to import external data on the fly, like data form CSV files,
+or dynamic queries against an Overpass API Server, this kind of data is not
+supported by this service yet though, and so will not be part of the generated
+print map.
+
+Note that the file will be stored on the web server, and that the map generated from it
+(but not the actual Umap file) will be visible to everyone. So do not upload any
+sensitive data you don't want to to be seen in public, or that you don't have the
+permission for to share it in public.
+
+image::umap-selected.png[Umap Preview,width=80%,pdfwidth=80%,align=center]
+
+Like with GPX uploads, once a valid Umap file has been selected for upload the form
+will switch back to the area selection tab and will show a simplified preview of the
+uploaded data.
+
+You can modify the selected area if you only want to show part of the Umap
+information, or actually want to show it in a larger map context.
+
+image:umap-result.png[Umap Render Result,width=45%,pdfwidth=45%]
+image:umap-actual.png[Umap Original Online Map,width=45%,pdfwidth=45%]
+
+An actually rendered Umap map may look like the example on the left hand side,
+while the right hand side shows how the original online Umap looks like.
+The results are not completely the same , especially when it comes to line stroke
+width, but this is mostly due to difference in size an resolution of the target
+devices, paper vs. screen. 
+
+
+
+Select a paper layout
+~~~~~~~~~~~~~~~~~~~~~
+
+In this step you can choose between different paper layouts.
+
+image::step-layout.png[Umap Preview,width=80%,pdfwidth=80%,align=center]
+
+There are three different single page layouts, and one for multi page
+booklets.
+
+The basic single  page layout uses the full page for the map.
+
+The other two single page layouts add a street index to the
+map, either on the side -- left side for left-to-write languages,
+or right side for right-to-left languages like Arabic or Hebrew --
+or at the bottom.
+
+The multi page layout creates a multi page booklet with a title
+page, an overview page, a collection of detail map pages, and
+a street index.
+
+The preview on the right hand side changes with your selection,
+it does not show the actual selected map area though. It is
+just using pre-rendered examples to give you a rough idea
+what each layout looks like.
+
+
+Select a map style
+~~~~~~~~~~~~~~~~~~
+
+Here you can select the style of the base map.
+
+image::step-style.png[Umap Preview,width=80%,pdfwidth=80%,align=center]
+
+Style selections are grouped by specific themes, e.g. for
+country specific styles. Only one base style can be selected.
+
+The preview on the right hand side again changes with your
+selection, and only shows a fixed pre-defined map area,
+not the area you actually chose, to give you a quick
+rough idea what the chosen style looks lie.
+
+Optionally: Select map overlays
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Map overlays are rendered on top of the basemap. They can
+either add decoration elements like a compas rose or scale
+bar, or additional special interest map features like
+hiking routes, fire hydrants or height contour lines.
+
+image::step-overlay.png[Umap Preview,width=80%,pdfwidth=80%,align=center]
+
+Overlay styles are also grouped by theme like the base styles,
+but here you can select multiple overlay styles, not just one.
+
+The preview on the right only shows the last overlay you
+selected, on top of the Black&White base style for better visibility
+of the overlay additions, not a combination of all selected overlays.
+
+
+Select paper size an orientation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In this step the minimal required paper size is calculated,
+and you are given a choice of predefined paper formats that
+are larger than this, plus a "best fit" option.
+
+image::step-papersize.png[Umap Preview,width=80%,pdfwidth=80%,align=center]
+
+You can also select the paper orientation here. The optimal
+orientation is pre-selected automatically, but you can override
+the default choice to fit your own needs.
+
+Select map title and language
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This is the final step before submiting the rendering job.
+Here you can select a map title, the language for map
+annotations, and optionally give your email address if
+you want to be informed via mail when your request has
+been processed.
+
+Also a quick summary of your choices is shown.
+
+image::step-submit.png[Umap Preview,width=80%,pdfwidth=80%,align=center]
+
+The map title is prefilled if you used the city selection
+to specify the map area. If you uploaded a GPX or Umap
+file the map title will also be prefilled if title information
+was found in the uploaded file.
+
+The chosen language is used for the annotations and copyright
+information at the bottom of the map, and for section titles
+in the street index. In the German style it also influences
+the language choice for actual map features, the other styles
+still use a fixed language setting so far though.
+
+If you provide an email address you will be notified when
+your rendering request has been processed successfully, or
+ran into an error. The email address entered here will
+only be stored for 48 hours, and will usually only be used
+to send the result notification. In case of rendering errors
+you may also receive feedback questions to help debugging
+the problem, and in case of a bug fixed you will be informed
+about a successful re-rendering of your request.
+
+
+Map styles
+----------
+
+
+
+
+Overlay styles
+--------------
+
+

www/maposmatic/templates/maposmatic/base-parts/navbar.html

@@ -0,0 +1,79 @@
+{% load i18n %}
+{% load extratags %}
+
+    <nav class="navbar navbar-default navbar-fixed-top">
+      <div class="container-fluid">
+
+        <div class="navbar-header">
+          <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
+            <span class="sr-only">Toggle navigation</span>
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+            <span class="icon-bar"></span>
+          </button>
+          <a 
+          rel="popover" 
+            data-animation="false"
+            data-html="true"
+            data-original-title="{% trans "Platform status" %}"
+            data-placement="bottom"
+            data-content='<p>{% trans "Rendering daemon: " %}<i class="pull-right glyphicon glyphicon-{% if daemon_running %}ok{% else %}remove{% endif %}"></i></p>
+            <p>{% trans "GIS database: " %}<i class="pull-right glyphicon glyphicon-{% if gis_lag_ok %}ok{% else %}{% if gis_lastupdate %}warning-sign{% else %}remove{% endif %}{% endif %}"></i></p>
+            <p>{% trans "WayMarked database: " %}<i class="pull-right glyphicon glyphicon-{% if waymarked_lag_ok %}ok{% else %}{% if waymarked_lastupdate %}warning-sign{% else %}remove{% endif %}{% endif %}"></i></p>'
+            class="navbar-brand popovered" href="#"><i class="glyphicon glyphicon-{{ platform_status }}"></i> {{BRAND_NAME}}</a>
+        </div>      
+
+        <div id="navbar" class="navbar-collapse collapse">
+          <ul class="nav navbar-nav">
+            <li class="{% block menu-home   %}{% endblock %}"><a href="{% url "main"   %}"><i class="glyphicon glyphicon-home"></i> {% trans "Home" %}</a></li>
+            <li class="{% block menu-new    %}{% endblock %}"><a href="{% url "new"    %}"><i class="glyphicon glyphicon-edit"></i> {% trans "Create map" %}</a></li>
+            <li class="{% block menu-maps   %}{% endblock %}"><a href="{% url "maps"   %}"><i class="glyphicon glyphicon-list"></i> {% trans "Maps" %}</a></li>
+
+	    <li class="dropdown">
+	      <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button"><i class="glyphicon glyphicon-comment"></i> {% trans "About" %} <b class="caret"></b></a>
+	      <ul class="dropdown-menu">
+		<li><a href="{% url "about"             %}"><i class="glyphicon glyphicon-comment"></i> {% trans "About Maposmatic" %}</a></li>
+		<li role="separator" class="divider"></li>
+		<li><a href="{% url "documentation_user_guide"  %}"><i class="glyphicon glyphicon-book"></i> {% trans "User Guide"     %}</a></li>
+		<li><a href="{% url "documentation_api"         %}"><i class="glyphicon glyphicon-book"></i> {% trans "API Docs"       %}</a></li>
+		<li role="separator" class="divider"></li>
+		<li><a href="https://github.com/hholzgra/maposmatic/" target="_blank"><i class="fa fa-github"></i> MapOSMatic project</a></li>
+		<li><a href="https://github.com/hholzgra/ocitysmap/" target="_blank"><i class="fa fa-github"></i> OCitysMap project</a></li>
+		<li><a href="https://github.com/hholzgra/maposmatic-vagrant/" target="_blank"><i class="fa fa-github"></i> MapOSMatic Vagrant Box</a></li>
+	      </ul>
+	    </li>
+
+	    
+	    {% if PAYPAL_ID %}
+            <li class="{% block menu-donate %}{% endblock %}"><a href="{% url "donate" %}"><i class="glyphicon glyphicon-gift"></i> {% trans "Donate" %}</a></li>
+	    {% endif %}
+
+            <li class="dropdown">
+              <a href="#" class="dropdown-toggle" data-toggle="dropdown">
+                <i class="glyphicon glyphicon-flag"></i> {{ LANGUAGES|getitem:LANGUAGE_CODE }} <b class="caret"></b>
+              </a>
+              <ul class="dropdown-menu">
+                <form action="/i18n/setlang/" method="post" name="langsel" class="navbar-form form-horizontal">
+                <input name="language" type="hidden" value="{{ LANGUAGE_CODE }}" />
+                {% for language in LANGUAGES_LIST %}
+                <li class="{% ifequal language.0 LANGUAGE_CODE %}active{% endifequal %}">
+                <a href="javascript:(function() { document.langsel.language.value = '{{ language.0 }}'; document.langsel.submit(); })();">{{ language.1 }}</a>
+                </li>
+                {% endfor %}
+                </form>
+              </ul>
+            </li>
+
+            <form action="{% url "maps" %}" method="get" class="navbar-form form-horizontal pull-right">
+              <div class="form-group">
+                <div class="input-prepend">
+                  <span class="add-on"><i class="glyphicon glyphicon-search"></i></span>
+                  {{ searchform.query }}
+                </div>
+              </div>
+            </form>
+
+          </ul>
+        </div>
+      </div>
+    </nav>

www/maposmatic/templates/maposmatic/documentation-api.html

@@ -0,0 +1,39 @@
+{% extends "maposmatic/base.html" %}
+
+{% comment %}
+ coding: utf-8
+
+ maposmatic, the web front-end of the MapOSMatic city map generation system
+ Copyright (C) 2012  David Decotigny
+ Copyright (C) 2012  Frédéric Lehobey
+ Copyright (C) 2012  Pierre Mauduit
+ Copyright (C) 2012  David Mentré
+ Copyright (C) 2012  Maxime Petazzoni
+ Copyright (C) 2012  Thomas Petazzoni
+ Copyright (C) 2012  Gaël Utard
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as
+ published by the Free Software Foundation, either version 3 of the
+ License, or any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+{% endcomment %}
+{% load i18n %}
+{% load extratags %}
+
+{% block body-class %}about{% endblock %}
+{% block menu-about %}active{% endblock %}
+
+{% block title %}{% trans "User Guide" %}{% endblock %}
+{% block page %}
+
+{% include "api-docs.html" %}
+
+{% endblock %}

www/maposmatic/templates/maposmatic/documentation-user-guide.html

@@ -0,0 +1,39 @@
+{% extends "maposmatic/base.html" %}
+
+{% comment %}
+ coding: utf-8
+
+ maposmatic, the web front-end of the MapOSMatic city map generation system
+ Copyright (C) 2012  David Decotigny
+ Copyright (C) 2012  Frédéric Lehobey
+ Copyright (C) 2012  Pierre Mauduit
+ Copyright (C) 2012  David Mentré
+ Copyright (C) 2012  Maxime Petazzoni
+ Copyright (C) 2012  Thomas Petazzoni
+ Copyright (C) 2012  Gaël Utard
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as
+ published by the Free Software Foundation, either version 3 of the
+ License, or any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <http://www.gnu.org/licenses/>.
+{% endcomment %}
+{% load i18n %}
+{% load extratags %}
+
+{% block body-class %}about{% endblock %}
+{% block menu-about %}active{% endblock %}
+
+{% block title %}{% trans "User Guide" %}{% endblock %}
+{% block page %}
+
+{% include "user-guide.html" %}
+
+{% endblock %}