Readthedocs import (#784)

* First rftd.io import

* Testing Markdown doc

* Testing Markdown doc

* Testing RST

* Datetime is required

* Testing RST

* Adding a basic configuration page from the wiki

* Testing RST

* Testing syntax highlighting

* Testing syntax highlighting

* Testing syntax highlighting

* Importing https://wiki.navit-project.org/index.php/Maps

* Importing https://wiki.navit-project.org/index.php/Maps

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/Binfile

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Importing https://wiki.navit-project.org/index.php/OpenStreetMap

* Fixing links

* Fixing links

* Fixing links

* Fixing links

* Fixing links

* Minor improvments

* Minor improvments

* Minor fixes

* Importing detailed configuration

* Improving the index page

* Removing copyright, it makes CodeFactor unhappy

* Added misspell checks

* Fixed wrong copy pasta

* Install curl, required to install misspell

* Fixed some typos

* Removed a bunch of trailing spaces

* Removed a bunch of trailing spaces

* Probably don't need "please" here.

* Reworking content

* Apply suggestions from code review

Remove unneeded white spaces before colon

* Apply suggestions from code review

Setting song for software or file names like the other occurences

* Update docs/binfile.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/advanced.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/advanced.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Removed wiki comment

* Update docs/configuration/display.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/display.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/general.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/general.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/general.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/index.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/index.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/layout.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/vehicle.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/vehicle.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/vehicle.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/vehicle.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/index.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/index.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/index.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/index.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Update docs/configuration/display.rst

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

* Apply suggestions from code review

Co-Authored-By: Joseph Herlant <aerostitch@users.noreply.github.com>

13 files changed, 1002 insertions, 0 deletions

diff --git a/docs/basic_configuration.rst b/docs/basic_configuration.rst
new file mode 100644
index 000000000..250a6686f
--- /dev/null
+++ b/docs/basic_configuration.rst
@@ -0,0 +1,66 @@
+There are much more options, see [[configuration]].
+
+Preparation
+===========
+Get a supported map package
+---------------------------
+Navit can use different :doc:`maps` formats, including free :ref:`OpenStreetMap` data. In order to use one of these maps, download a map of your desired area and store it into a local folder (such as navit/maps or /usr/share/navit/maps).
+
+Install TTS
+-----------
+To get speech support, you need to install a text-to-speech tool such as **espeak**, **mbrola** or **festival**. These tools can be invoked from the command line. Test your setup by invoking the tools manually e.g.
+
+.. code-block:: bash
+
+  espeak "This is a text!"
+
+On some systems Navit comes with integrated espeak support, so you don't need to download it separately.
+
+Connect GPS
+-----------
+Now connect your GPS. The exact procedure for this varies depending on the type of GPS device you are using and how you connect it to your computer. On Linux / Unix systems, your GPS should typically show up as a character device, i.e., you will find an entry in the /dev folder corresponding to your GPS device. Again, the file name depends on the type and connection method of your GPS receiver. See [[Connecting a GPS receiver]] for details.
+
+Most GPS receiver will output the position in [[NMEA]] format, which can be used directly in Navit or using a GPS daemon program such as **gpsd**. A simple way to test whether your GPS receiver works and outputs NMEA data is to dump its output to a console. For example, if your GPS receiver can be found at **/dev/rfcomm0**, you can dump its output using
+
+.. code-block:: bash
+
+   cat /dev/rfcomm0
+
+The output should give you steady NMEA position updates. You can feed this information into **gpsd** / **xgps** or **QLandkarte** to see a graphical representation of your position and to check whether the output corresponds to your current position.
+
+Configuring
+===========
+
+Currently Navit doesn't provide a graphical tool to change settings, so you have to do the changes manually using a texteditor.
+Please open your current **navit.xml** file and do the following steps:
+
+
+Setup proper startup-position
+-----------------------------
+On Navit's very first startup, it needs a **center** to look at on the map. By default this is set to Munich in Germany (at latitude 48.08 and longitude, which is conveniently covered by the sample map created on installation).
+
+.. code-block:: xml
+
+   <navit center="4808 N 1134 E" />
+
+See furthermore: [[Configuration]]
+
+
+Setup GPS
+---------
+Add the GPS connection
+
+.. code-block:: xml
+
+   <vehicle name="My" enabled="yes" source="file://dev/ttyS0"/ active="1"/>
+
+See furthermore: [[Configuration]]
+
+
+Enable Map
+----------
+Just change the map entry corresponding to your local folders
+
+.. code-block:: xml
+
+  <map type="binfile" enabled="yes" data="/var/navit/maps/uk.bin" />
diff --git a/docs/binfile.rst b/docs/binfile.rst
new file mode 100644
index 000000000..572ebbe19
--- /dev/null
+++ b/docs/binfile.rst
@@ -0,0 +1,122 @@
+Binfile
+-------
+
+Navit has its own map format, called **binfile** format. It's a binary format, optimized for use with Navit (rendering, search, routing on embedded devices).
+
+Dividing the world into tiles
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The map coordinates of binfile are in meters, measured from equator and null meridian, with a merkator projection. The limit of this world is about 20000 km in earch direction from this null point. This doesn't cover polar regions, but it's ok for now.
+
+So, the world gives a 40000x40000km rectangle (tile). This rectangle is divided into 4 equally-sized sub-rectangles (tiles) called a,b,c and d counter clockwise ...
+
+* a is top right
+* b top left
+* c bottom right
+* d bottom left
+
+Each of the sub-rectangles (tiles) is then further subdivided, so a rectangle "aa" is top right in "a"
+
+This is continued further up to 14 levels (but the number of levels might be variable). So in the end you get many tiles which are containing objects which are within this tile... And the tiles are also containing references to tiles which are within them.
+
+A Navit binfile is actually a ZIP file; each tile is a member file in a zip file. So to extract an area of this file, you just read the zip file sequentially.
+
+If you extract a small binfile using a zip tool, you will see member files
+adbdbbbbadcacd, adbdbbbbadcacd, ... . Each file contains the data for one tile.
+
+Projection
+~~~~~~~~~~
+
+The coordinates are projected using a modified "Google" (i.e. EPSG900913) projection.
+Navit assumes an earth radius of 6371000m rather than the WGS84 value of 6378137m. Thus, for navit, the circumference of the earth is (2 x 20015087m).
+
+Tile data format
+~~~~~~~~~~~~~~~~
+
+A tile itself is a dynamic data structure.
+
+As declared in `navit/map/binfile/binfile.c`__, a tile is represented in memory by a struct :
+
+.. code-block:: c
+
+ struct tile {
+   int *start;           /* Memory address of the whole data structure */
+   int *end;             /* Memory address of first memory address not belonging to tile
+                          * thus tile->end - tile->start represents the size of the tile
+                          * in multiples of 4 Bytes */
+   int *pos;             /* current position inside the tile */
+   int *pos_coord_start; /* pointer to the first element inside the tile that is a
+                          * coordinate. That is the first position after the header of a
+                          * tile. The header holds 3 entries each 32bit wide integers.
+                          * header[0] holds the size of the whole data-structure.
+                          * header[1] holds the type of the item
+                          * header[2] holds the size of the coordinates in the tile */
+   int *pos_coord;       /* current position inside the coordinates region within the tile */
+   int *pos_attr_start;  /* pointer to the first attr //TODO explain attr format// data
+                          * structure inside the tile's memory region */
+   int *pos_attr;        /* current position inside the attr region */
+   int *pos_next;        /* link to the next tile */
+   int zipfile_num;
+ }
+
+
+Content
+~~~~~~~
+Inside the binfile, each tile file contains a list of items. Each item is stored like this (everything is 4 bytes wide and always aligned):
+
+.. code-block:: c
+
+   {
+     int: Length of the item (not including this length field) in integers
+     int: Type of the item (from item_def.h)
+     int: Length of the coordinate data which follows in integers
+     {
+       int: pairs of coordinates with consisting of 2 integers each
+     } 0..n
+     {
+       int: length of the attribute (not including this length field) in integers
+       int: Type of attribute (from attr_def.h)
+       {
+         int: Attribute data, depending on attribute type
+       } 0..n
+     } 0..n
+   }
+
+Extracting a specific area
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can calculate the bounding box of the current tile.
+
+Then there are two possibilities:
+
+* The tile overlaps with the area you are interested in: Then simply copy the whole file data, including its header to the output, and add an entry to the directory which will be written later
+* The tile doesn't overlap: Then don't drop that file, but instead write a file with size 0 and the same name to the output (I will explain later why this is needed), and add an entry to the directory
+
+At some point you will have reached the end of the zip files, then you have to write the zip directory and the "end of directory" marker.
+
+This will be very fast (you don't have to look into the zip files, which would mean decompressing and compressing them again) but has some disadvantages:
+
+* You will have many empty files in it which are not really necessary. This is needed because the reference to sub-tiles are by number, and not by name (would be slow), and so the position of a tile within the zip file is not allowed to change
+* You get some data you didn't want to have: this is because a tile which overlaps with your area of course doesn't contain only data from your wanted area, but from the area where it is located
+
+
+How an object is placed in a tile
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+An object is placed inside of a tile using the following approach
+
+* If the object can fit into one of the 4 top tiles it is placed in that tile
+
+* The 4 sub-tiles are then checked to see if the object will fit inside of any of the four tiles that are contained inside of the sub-tile.  If so, it is moved down a tile.  This step is repeated until the object spans 2 or more tiles (or the lowest tile level is reached)
+
+* If the object can't fit inside of any of the 4 top sub-tiles it is placed inside of the top-most tile
+
+An object 'fits' inside of a tile if the coordinates of the object (min lat, min lon, max lat, max lon) lie inside of the coordinates of the tile (tile_min_lat, tile_min_lon, tile_max_lat, tile_max_lon)
+
+Any object that cross the equator or the poles is placed in the top-most tile because it can not fit inside of any sub-tile.
+
+Some important objects are placed into upper level tiles despite of their length to be easier reachable for routing or display purposes. This is done by specifying maximum tile name length for them in phase34_process_file() function in `navit/maptool/misc.c`__.
+
+BTW, "order" (zoom level) values used to query map and referred in <itemgra> and route_depth are equal to (tile_name_length-4).
+
+.. __: https://github.com/navit-gps/navit/blob/trunk/navit/map/binfile/binfile.c
+.. __: https://github.com/navit-gps/navit/blob/trunk/navit/maptool/misc.c
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 000000000..a8b73e774
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,11 @@
+# -*- coding: utf-8 -*-
+from datetime import datetime
+
+source_suffix = '.rst'
+
+master_doc = 'index'
+
+# General information about the project.
+project = u'navit'
+year = datetime.now().year
+author = u'The Navit Team'
diff --git a/docs/configuration/advanced.rst b/docs/configuration/advanced.rst
new file mode 100644
index 000000000..68066af03
--- /dev/null
+++ b/docs/configuration/advanced.rst
@@ -0,0 +1,101 @@
+Advanced Options
+================
+The rest of this webpage is meant for advanced/power users who'd like to fiddle a little more under-the-hood. The average user can safely ignore this section!
+
+Speech
+------
+Navit can announce driving directions with voice. Navit can use different mechanisms to play these announcements.
+Note that not all tools are available on all platforms.
+
+Prerecorded samples
+~~~~~~~~~~~~~~~~~~~
+Navit is able to compose phrases if you give it a set of prerecorded **samples**. Configuration example:
+
+.. code-block:: xml
+
+    <speech type="cmdline" data="aplay -q %s"
+    sample_dir="/path/to/sampledir" sample_suffix=".wav" flags="1"
+    vocabulary_name="0" vocabulary_name_systematic="0" vocabulary_distances="0"/>
+
+
+The directory ''sample_dir'' should contain audio files. ''sample_suffix'' is the common file type suffix of those files. The names of the files (without the suffix) must correspond to the text they contain. For each text it wants to speak, Navit will look for one or more sample files with corresponding names (ignoring upper/lower case). So for "turn right in 300 meters" you could use turn.wav, right.wav, in.wav, 300.wav, meters.wav. Navit will prefer files that contain multiple words: If file "turn right.wav" is present, it will be used even if you have turn.wav and right.wav.
+
+Note that Navit internally handles all text in UTF-8 encoding. If you use a file system where file names are not encoded with UTF-8 (such as Windows), Navit will only find files for ASCII text. If you use a language that uses non-ASCII characters, the file name must be the [http://en.wikipedia.org/wiki/Percent-encoding percent encoding] of the UTF-8 representation of the text. For example the filename for "süd" would be "s%c3%bcd.wav" (because "ü" is encoded as C3BC in UTF-8). For this feature to work, you must set ''flags'' to 1.
+
+''data'' is the program that can be used to play the sample files. You should specify the program name along with any necessary parameters. The placeholder "%s" will be replaced with the file(s) to be played. All files required for a text will be passed in one go, so the program will need to support playing multiple files. Note that the %s should ''not'' be quoted; the text is not passed through a shell.
+
+Note that if any file that is needed to compose the complete phrase is missing then Navit will be silent. In that case a warning will be printed. Unfortunately, there is no complete list of the samples required. However, all the navigation text is contained in the translation files (.po files), so you can get a rough list.
+
+By default Navit is trying to announce street names. To disable this feature you can set ''vocabulary_name'' and ''vocabulary_name_systematic'' to 0 in the speech tag which will specify that the speech synthesizer isn't capable of speaking names. Also there is ''vocabulary_distances'' which you can set to 0 so only the minimum set of 1,2,3,4,5,10,25,50,75,100,150,200,250,300,400,500,750 as numbers is used.
+
+espeak
+~~~~~~
+.. code-block:: xml
+
+ <speech type="cmdline" data="espeak -s 150 -v english_rp %s"/>
+
+Will use espeak instead, for those who want Navit to speak to them in English, at 150 words per minute. The ''%s'' is filled in by Navit when sent to the speech synthesis software (with something like "Turn left" or whatever is appropriate at the time). If you need more features, you should use an external wrapper script which can contain anything supported by your shell (see [[Translations]]).
+
+festival
+~~~~~~~~
+
+flite
+~~~~~
+
+Mbrola
+~~~~~~
+
+Android
+~~~~~~~
+
+.. code-block:: xml
+
+ <speech type="android" cps="15"/>
+
+
+Start up in silent mode
+~~~~~~~~~~~~~~~~~~~~~~~
+To have Navit start up in silent mode, insert ``<code>active="0"</code>`` somewhere in your ``<code>speech</code>`` tag. For example on Android:
+
+.. code-block:: xml
+
+ <speech type="android" cps="15" active="0"/>
+
+
+In this case, you should place a <code>toggle_announcer</code> item in your [[OSD]] configuration, or add a menu item so you can enable speech output when you need it.
+
+
+Splitting navit.xml
+-------------------
+Navit has support for a small subset of **XInclude** / **XPath** for including parts of external XML files. Supported is a tag like
+
+.. code-block:: xml
+
+ <xi:include href="some_file" xpointer="xpointer_stuff" />
+
+
+You can leave out either href (xi:include refers to the same file it is in then) or xpointer (xi:include then refers the complete file), but not both. The ''href'' attribute refers to a file relative to the current directory. It is suggested to use the complete path, such as ''/home/root/.navit/navit-vehicles.xml''.
+
+href is expanded with wordexp internally, so you can do stuff like:
+
+.. code-block:: xml
+
+ <xi:include href="$NAVIT_SHAREDIR/maps/*.xml" />
+
+Some examples on the supported syntax:
+.. code-block:: xml
+
+ <xi:include xpointer="xpointer(/config/navit/layout[@name='Car']/layer[@name='points'])" />
+
+references to the XML-Tag "layer" with attribute "name" of value "points" within an XML-Tag "layout" with attribute "name" of value "Car" within an XML-Tag "navit" within an XML-Tag "config".
+
+.. code-block:: xml
+
+ <config xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="$NAVIT_SHAREDIR/navit.xml" xpointer="xpointer(/config/*[name(.)!='navit'])"/>
+ <navit center="4808 N 1134 E" zoom="256" tracking="1" cursor="1" orientation="0">
+ <xi:include href="$NAVIT_SHAREDIR/navit.xml" xpointer="xpointer(/config/navit/*[name(.)!='vehicle'])"/>
+ </navit>
+ </config>
+
+Use this as your ``$HOME/.navit/navit.xml`` and you will get everything under ``<config>..</config>`` except ``<navit>..</navit>`` (first ``xi:include``), plus ``<navit>`` as specified plus everything from navit within config, except the vehicle definitions (second ``xi:include``).
diff --git a/docs/configuration/display.rst b/docs/configuration/display.rst
new file mode 100644
index 000000000..f822d053b
--- /dev/null
+++ b/docs/configuration/display.rst
@@ -0,0 +1,111 @@
+Display Options
+---------------
+The Navit display is highly customisable and consists of the following components
+
+* Graphics driver (appropriate engine for your system, to draw everything)
+* GUI (enables user interaction and map display)
+* OSD (shows widgets on map screen)
+
+Graphics Driver
+---------------
+
+Different technologies can be used, to let Navit draw it's visual components. Not all might be available at your specific system
+
+The current list of available graphics drivers:
+
+* **android**, for the Android port
+* **cocoa**, for the iPhone port
+* **gtk_drawing_area**,  usually most appropriate on Linux desktop systems
+* **sdl**, render inside an X window, or direct to the Linux framebuffer, with min dependencies on external libraries.
+* **qt5**, render using Qt5 library, either using QWidgets or QML. On top of any Qt5 supported display technology.
+* **win32** - useable with <tt>gtk</tt> or <tt>internal</tt> GUIs for Windows systems only.
+
+Experimental/less maintained drivers:
+
+* **qt_qpainter**, render inside X window or on top of Qt Palmtop Environment.
+* **opengl**, rendering via OpenGL
+* **gtk_gl_ext**, rendering via OpenGL using GTK+ OpenGL extension
+* **gd**, rendering using the GD Graphics Library
+
+They can be activated and configured as following:
+
+.. code-block:: xml
+
+ <graphics type="gtk_drawing_area"/>
+
+As mentioned, it's usually best to leave this as whatever the default is within your :xml:`navit.xml`, and only mess around with it if you know what you are doing, or have been told to by one of the developers.
+
+Graphical User Interface
+------------------------
+You can now choose which type of GUI you would like to use with Navit. Not all GUIs work with all Graphics drivers
+
+
+======== ======= ===== ==== ================ ========== ====== =========== === ===== === =======
+GUI      android cocoa gd   gtk_drawing_area gtk_gl_ext opengl qt_qpainter sdl win32 qt5 preview
+======== ======= ===== ==== ================ ========== ====== =========== === ===== === =======
+GTK
+Internal Yes     Yes   Yes  Yes              Yes        Yes    Yes         Yes Yes   Yes
+QML2
+======== ======= ===== ==== ================ ========== ====== =========== === ===== === =======
+
+Generic GUI Options
+~~~~~~~~~~~~~~~~~~~
+There are some options available for the ``gui`` tag which are used by all the GUI types. These include:
+
+* **fullscreen** - Enables Navit to start in fullscreen mode.
+* **pitch** - The pitch value to pitch the map to when selecting 3D mode from the menus.
+* **dimensions** - w="1024" h="600"
+
+The following example uses the :xml:`internal` GUI, and starts Navit up in fullscreen mode, and will pitch the map to 35 degrees when 3D mode is selected from the menu. Note that to start Navit in 3D mode by default, [[#Initial 3D pitch|change the :xml:`pitch` value in the :xml:`navit` tag]]:
+
+.. code-block:: xml
+
+ <gui type="internal" enabled="yes" fullscreen="1" pitch="35">
+
+Internal GUI
+~~~~~~~~~~~~
+The first GUI is embedded in Navit core and is primarily aimed at [[touchscreen]] devices, or those devices with small screens (such as netbooks). However, this GUI also works very well on desktops and laptops.
+
+.. code-block:: xml
+
+ <gui type="internal" enabled="yes">
+
+Options
+^^^^^^^
+A number of options specific to the ``internal`` GUI are available. These include:
+
+* **font_size** - Base text size to use within the ``internal`` menu.
+* **icon_xs** - The size that extra-small style icons should be scaled to (e.g. country flag on town search).
+* **icon_s** - The size that small style icons should be scaled to (e.g. icons of ``internal`` GUI toolbar).
+* **icon_l** - The size that large style icons should be scaled to (e.g. icons of internal GUI menu).
+* **menu_on_map_click** - Toggles the ability to bring up the menu screen when clicking on the map. See the [[Internal_Gui#Menu_Configuration|``internal`` GUI page]] for more information.
+
+An example ``gui`` tag using the previous options is shown below:
+
+.. code-block:: xml
+
+ <gui type="internal" enabled="yes" font_size="250" icon_xs="48" icon_s="48" icon_l="64">
+
+More options are discussed on the [[Internal Gui]] and the [[Configuration/Full_list_of_options|full list of options]].
+
+GTK GUI
+~~~~~~~
+The second GUI is called **gtk**, and is most useful for those users who wish to use a traditional windowed GUI. This is one useful to desktop use.
+
+.. code-block:: xml
+
+ <gui type="gtk" enabled="yes" ... />
+
+
+Options
+^^^^^^^
+A number of options specific to the ``gtk`` GUI are available. These include:
+
+* menubar - enable/disable the menubar
+* toolbar - enable/disable the toolbar
+* statusbar - enable/disable the statusbar
+
+
+.. code-block:: xml
+
+ <gui type="gtk" enabled="yes" menubar="1" toolbar="1" statusbar="1"/>
diff --git a/docs/configuration/general.rst b/docs/configuration/general.rst
new file mode 100644
index 000000000..2ad2874d7
--- /dev/null
+++ b/docs/configuration/general.rst
@@ -0,0 +1,83 @@
+==General Options==
+Settings which affect Navit's general behaviour are located within the ``<navit .. >`` tag. In a default installation, this is found on line 31 of ``navit.xml``. By default, the ``navit`` tag is set as follows:
+
+.. code-block:: xml
+
+<source lang="xml">
+ <navit center="4808 N 1134 E" zoom="256" tracking="1" orientation="-1" recent_dest="10">
+</source>
+
+Some common attributes are discussed below. For more advanced features, see [[Configuration/Full_list_of_options | the full list of options]].
+
+===Initial map position===
+On Navit's very first startup, it needs a **center** to look at on the map. By default this is set to Munich in Germany, which is conveniently covered by the sample map created on installation.
+
+
+.. code-block:: xml
+
+<source lang="xml">
+ center="11.5666 48.1333"
+</source>
+
+Coordinates can be written in different formats; see [[Coordinate_format]] for the full list.
+To determine a specific latitude and longitude for your location you can use http://itouchmap.com/latlong.html.
+Usually, changing the "center" setting is not necessary, since it is only used during the first start.
+On subsequent starts, Navit will remember the last map position (stored in "center.txt") and ignore the "center" setting.
+
+When Navit starts, it will display the map at a pre-defined **zoom**. The default zoom level is 256. The lower the value, the closer you will be zoomed in. <!---what does the zoom number express? How can I estimate it?-->
+
+ zoom="256"
+
+For those using the [[SDL GUI]], a level of 128 is recommended.
+
+ zoom="128"
+
+Note that once Navit has started, the zoom level can be altered using [[OSD]] or menu items.
+
+
+Use the **orientation** attribute to orient the map in either the direction of travel, or oriented North. .To orient the map in the direction of travel:
+
+ orientation="-1"
+
+or to orient North:
+
+ orientation="0"
+
+Orienting the map North whilst in [[3D]] mode will provide visually confusing results, and is not recommended. When in 3D mode, it's best to have the map oriented in the direction of travel.
+
+===Autozoom===
+Navit has the ability to **autozoom** the map in or out dependent upon your speed.
+
+ autozoom_active="1"
+
+To de-activate autozoom:
+
+ autozoom_active="0"
+
+===3D pitch===
+Navit has the capability to display either a 2D map (bird's eye perspective) or a [[3D]] map (some amount of tilt looking to the horizon). Navit's default configuration is to startup in the 2D perspective but it is possible to specify that Navit start with a 3D perspective. The amount of tilt is specified by setting the value of <tt>pitch</tt>.
+
+The **pitch** value defines default camera tilting, with a value from 0 to 359. Note that usable values lie between 0 and 90 where 0 is bird's eye perspective looking down and 90 is human perspective looking forward. Also note that values closer to 90 will slow down map drawing, because the line of sight gets longer and longer and more objects are seen.
+
+For example, the following added to the <tt>navit</tt> tag will force Navit to start with a pitch of 30 degrees:
+
+ pitch="30"
+
+===Imperial units===
+By default, Navit use the metric system of measurements when displaying or announcing distances, speeds etc. However, you can configure Navit to display and announce these values in imperial units. Simply add an <tt>imperial</tt> attribute to the Navit tag, and set its value to 1, as shown below:
+
+ imperial="1"
+
+Speeds should now be displayed in units of miles-per-hour, whilst distances are converted to miles (large distances) and feet (small distances).
+
+===Default layout===
+When no specific layout has been specified by the user, navit uses a default layout to draw maps.
+The  <tt>default_layout</tt> attribute of the navit tag allows to specify which layout to use as default;
+
+ default_layout="Car"
+
+This string should match the <tt>name</tt> attribute of the required <tt><layout></tt> tag.
+
+See [[Configuration/Layout_Options| layout options]] for more details.
+[[Category:Customizing]]
+[[Category:Configuration]]
diff --git a/docs/configuration/index.rst b/docs/configuration/index.rst
new file mode 100644
index 000000000..38504d067
--- /dev/null
+++ b/docs/configuration/index.rst
@@ -0,0 +1,143 @@
+Navit is highly modular and customizable. This page aims to point out the most common options which a first-time user may want to change - power users may want to consult [[Configuration/Full_list_of_options | the full list of options]].
+It is also possible to edit the navit.xml file for your Android device under Windows and Linux (Debian/Ubuntu derivates) with a third party application called [[NavitConfigurator]].
+
+Setting up Navit is done by editing a configuration file called "**navit.xml**".
+Editing XML configurations files in a text editor is simple, they are just plain text XML files, that can be edited with any editor. Just remember to ''turn off 'save UTF8 byte mark' in Preferences'' or navit may complain very much on the first byte of the file.<br>
+The XML configuration file is splitted into sections within a hierarchy:
+
+.. code-block:: xml
+
+<source lang="xml">
+<config>
+  <plugins></plugins>
+  <navit>
+    <osd></osd>
+    <vehicle></vehicle>
+    <vehicleprofile></vehicleprofile>
+    <mapset></mapset>
+    <layout></layout>
+  </navit>
+</config>
+</source>
+
+Navit comes **preshipped** with a default ``navit.xml`` together with ``navit_layout_*.xml`` files that are stored at various locations (depending on your system). For Linux-like OSes:
+* in ``~/.navit/``: e.g: ``/home/myusername/.navit/navit.xml`` (This is probably to best place to customize your settings!)
+* in ``/usr/share/navit`` or ``/etc/navit``
+
+Navit will apply settings in the following order:
+* in the current directory (used on Windows)
+* location supplied as first argument on the command line, e.g.: ``navit /home/myusername/navittestconfig.xml`` (Used mainly for development)
+* in the current directory as ``navit.xml.local`` (Used mainly for development)
+
+{{note
+|In any case, you have to **adapt settings** to your system!<br> This includes especially GPS, map provider and vehicle: [[Basic configuration]]
+}}
+
+=Configurable Sections=
+<div style="margin-bottom:8px;">
+{| cellpadding=3 cellspacing=1
+
+<!-- GENERAL -->
+| width="33%" valign="top" style="background:#FFFFFF; border:2px solid #478cff;" |
+{| style="width:100%; vertical-align:top; background:#FFFFFF;"
+! style="padding:2px" | <h2 style="margin:3px; background:#478cff; font-size:120%; font-weight:bold; border:1px solid #478cff; text-align:left; color:#fff; padding:0.2em 0.4em;">General</h2>
+|-
+| style="margin:2px; padding:10px;" |
+
+Common options such as units, position, zoom and map orientation, ... be configured in this section.
+
+[[Configuration/General_Options| General options.]]
+
+|}
+
+| style="border:1px solid transparent;" |
+
+| width="33%" valign="top" style="background:#FFFFFF; border:2px solid #48be1f; margin-top:50px;" |
+<!-- DISPLAY -->
+{| style="width:100%; vertical-align:top; background:#FFFFFF;"
+|-
+! style="padding:2px" | <h2 style="margin:3px; background:#48be1f; font-size:120%; font-weight:bold; border:1px solid #48be1f; text-align:left; color:#fff; padding:0.2em 0.4em;">Display</h2>
+|-
+| style="margin:2px; padding:10px;" |
+
+A large number of display properties can be configured, including desktop or touchscreen-optimised GUIs, on-screen display items and complete control over menu items.
+
+[[Configuration/Display_Options| Display options.]]
+
+|}
+
+| style="border:1px solid transparent;" |
+
+
+<!-- VEHICLE -->
+| width="33%" valign="top" style="background:#FFFFFF; border:2px solid #e79e00;" |
+{| style="width:100%; vertical-align:top; background:#FFFFFF;"
+! style="padding:2px" | <h2 style="margin:3px; background:#e79e00; font-size:120%; font-weight:bold; border:0px solid #e79e00; text-align:left; color:#fff; padding:0.2em 0.4em;">Vehicle</h2>
+|-
+| style="margin:2px; padding:10px;" |
+
+A number of vehicles can be defined within Navit, depending upon the device and/or operating system in use. Vehicle profiles for routing (eg: car, pedestrian, bicycle...) are also completely configurable.
+
+[[Configuration/Vehicle_Options| Vehicle options.]]
+
+|}
+|}
+</div>
+
+<div style="margin-bottom:8px;">
+{| cellpadding=3 cellspacing=1
+
+<!-- MAPS -->
+| width="33%" valign="top" style="background:#FFFFFF; border:2px solid #ec7312;" |
+{| style="width:100%; vertical-align:top; background:#FFFFFF;"
+! style="padding:2px" | <h2 style="margin:3px; background:#ec7312; font-size:120%; font-weight:bold; border:1px solid #ec7312; text-align:left; color:#fff; padding:0.2em 0.4em;">Maps</h2>
+|-
+| style="margin:2px; padding:10px;" |
+
+You can use maps from a variety of sources, any number of maps can be configured and enabled at any one time.
+
+[[Configuration/Maps_Options| Maps options.]]
+
+|}
+
+| style="border:1px solid transparent;" |
+
+<!-- LAYOUT -->
+| width="33%" valign="top" style="background:#FFFFFF; border:2px solid #b30800;" |
+{| style="width:100%; vertical-align:top; background:#FFFFFF;"
+! style="padding:2px" | <h2 style="margin:3px; background:#b30800; font-size:120%; font-weight:bold; border:1px solid #b30800; text-align:left; color:#fff; padding:0.2em 0.4em;">Layout</h2>
+|-
+| style="margin:2px; padding:10px;" |
+
+Maps are displayed according to the rules defined in the layout. All aspects of the layout are configurable, from POI icons to colours for a particular type of highway.
+
+For all versions shipped after nov 2018, layout XML configuration is stored in dedicated XML files called with the prefix **navit_layout_** (one file per layout definition).
+
+[[Configuration/Layout_Options| Layout options.]]
+
+|}
+
+| style="border:1px solid transparent;" |
+
+<!-- ADVANCED -->
+| width="33%" valign="top" style="background:#FFFFFF; border:2px solid #992667;" |
+{| style="width:100%; vertical-align:top; background:#FFFFFF;"
+! style="padding:2px" | <h2 style="margin:3px; background:#992667; font-size:120%; font-weight:bold; border:1px solid #992667; text-align:left; color:#fff; padding:0.2em 0.4em;">Advanced</h2>
+|-
+| style="margin:2px; padding:10px;" |
+
+There are many more options, including debugging, specific plugins, speech announcements,  trip logging, ...
+
+[[Configuration/Advanced_Options| Advanced options.]]
+
+|}
+
+
+|}
+</div>
+
+<!-- Following line disables table of contents -->
+__NOTOC__
+
+[[Category:Customizing]]
+[[Category:Configuration]]
diff --git a/docs/configuration/layout.rst b/docs/configuration/layout.rst
new file mode 100644
index 000000000..31a41366d
--- /dev/null
+++ b/docs/configuration/layout.rst
@@ -0,0 +1,71 @@
+==Layout Options==
+===Layouts===
+A layout defines how to **render a map**.  Layouts are fully customisable, from the road colours and widths to size and type of icons to display for specific POIs. The layout is also where the **cursor** (i.e. the shape which shows where you are) is defined.<br>
+A number of user-generated layouts and cursor definitions are available at [[Layout]].
+
+===Defining layers===
+A layout consist of one cursor and one or more **layers** which are each a set of rules on how and when to draw certain items. Those rules are called **itemgra**. The layers are rendered one by one in the order they appear in the XML config file, as are the items in each layer. If you can't see an item make sure there is not another one hiding it. If your item is hidden, you can move your item further down in the layout section of the file.
+
+
+.. code-block:: xml
+
+<source lang="xml">
+ <layout name="Demo layout" color="#ffefb7" font="Liberation Sans" active="1">
+	<cursor w="26" h="26">
+	<layer name="layer_1">
+		<itemgra item_types="water_poly" order="0-">
+			<polygon color="#82c8ea" />
+		 	<polyline color="#5096b8" />
+		 </itemgra>
+	</layer>
+ <layout>
+</source>
+
+
+Here the available options:
+* item_types: Comma separated list of items (see navit/item.h for definitions)
+* order: Range for zoom levels.
+* speed_range: Range for vehicle speed, useful for cursors.
+* angle_range: Range for pitch angle.
+* sequence_range: Useful for animated cursors.
+
+For infos about map icons, see [[Icons]]
+
+===Overriding default (shipped) layouts===
+When the XML config file is parsed, layouts are taken in the order they come, and a layout with an already existing name overrides a previous definition.
+The default (shipped) navit.xml includes first system-wide navit_layout_*.xml files then the user-specific navit_layout_*.xml files, so the system-wide navit_layout_*.xml files can be overiden by adding a user-specific navit-layout_*.xml containing the same **name** attribute.
+
+Copying the default **navit.xml** file to the user-specific location will still use the default shipped layout files, but copying one or several layout files as well to the user-specific location (and modifying them) allow to override these specific layouts.
+
+===Note on the default layout used by navit===
+When no layout has been specifically selected by the user (for example at first startup), navit will use the default layout specified (see [[Configuration/General_Options#Default_layout|the related section to know how to configure this]]).
+
+===Using a layer in multiple layouts===
+Sometimes, multiple layouts can use the same layer. For example, a reduced layout for a cleaner map may use the same layers as the regular layout, just not all of them.
+
+To use a layer in multiple layouts, it can be referenced using the **ref** attribute. In place of the regular layer definition, use an empty tag with only the attributes ''name'' and ''ref'':
+
+<source lang="xml">
+<layer name="Found items" order="0-">
+    <itemgra item_types="found_item">
+        <circle color="#008080" radius="24" width="2" text_size="12"/>
+    </itemgra>
+</layer>
+[...]
+<layout name="Demo layout">
+    [...]
+    <layer name="Found items for demo layout" ref="Found items" />
+    [...]
+</layout>
+<layout name="Demo layout reduced">
+    [...]
+    <layer name="Found items" ref="Found items" />
+    [...]
+</layout>
+
+</source>
+
+Note that the layer you want to reuse must be placed ''outside'' the layout. Layers defined inside a layout cannot be reused in this way.
+
+[[Category:Customizing]]
+[[Category:Configuration]]
diff --git a/docs/configuration/vehicle.rst b/docs/configuration/vehicle.rst
new file mode 100644
index 000000000..3d1769b9f
--- /dev/null
+++ b/docs/configuration/vehicle.rst
@@ -0,0 +1,117 @@
+==Vehicle Options==
+It's important to understand the separate but linked Navit concepts of a **vehicle** and [[Vehicleprofile| **vehicleprofile**]] element. A vehicle defines the source of positional data (suchas a USB GPS device), and how to present that data to the user on the map, where the vehicleprofile defines all aspects of routing.
+
+A simple vehicle definition looks like this:
+
+
+.. code-block:: xml
+
+<source lang="xml">
+  <vehicle name="My" enabled="yes" source="file://dev/ttyS0"/ active="1"/>
+</source>
+
+
+Here some of the available options:
+* **active**: If set to 1, makes the vehicle the default active one. Routing, view centering and map redraw would be applied to this one by default.
+* **enabled**: If set to yes, Navit connects to the vehicle data source and shows the vehicle on the map.
+* **follow**: map follows after "n" gps updates (where n=0 means only when the vehicle leaves the map->saving CPU time)
+* **source** : source of GPS (required)
+* **profilename**: link the vehicleprofile for this vehicle.
+
+<!-- do we need to keep this keys or note them elsewhere?
+Obsolete options:
+* **update**: This will force the map to be recentered at your main cursor's position.
+* **color**/**color2**: The color of the cursor is now specified within the cursor tag itself.
+* **animate**: If set to 1, the cursor will be animated as a moving dotted line, to make it easier to see.
+-->
+
+===GPS===
+Most essential detail is the gps source, that need to be adapted to your local setup.
+
+
+**Local:**
+
+Windows:
+* source="serial:COM2 baud=4800 parity=N data=8 stop=1"
+** For Locosys GT31 (or BGT31 plugged by USB), settings are: source="serial:COM3 baud=38400 parity=N data=8 stop=1" where COM3 should be replaced by the correct COM over USB number.
+
+Windows Mobile:
+* source="wince:GPD1:" - using the internal GPS driver, configured from Windows Remote GPS Settings.
+** To use a BT GPS it must be configured as outgoing com port and paired, then selected as hardware port in GPS Settings.
+** To start bluetooth on navit startup add bluetooth="yes". When exiting navit, the previous bluetooth state is recovered.
+* source="wince:COM1:" baudrate="57600"
+
+There is useful [http://w5.nuinternet.com/s660100031/SirfTech.htm. SirfTech utility] that can  automatically scan existing serial ports trying different baudrates to detect GPS source.
+
+Linux:
+* source="file:/dev/rfcomm0"	- BlueTooth GPS
+* source="file:/dev/ttyS0"	- serial GPS connected to the first serial port (you may need to add the correct baudrate eg.: freerunner source="file:/dev/ttySAC1" baudrate="9600")
+* source="gpsd_dbus:"           - via dbus, position reported by gpsd
+
+**Network based:**<br>
+If you want to connect multiple tools to your GPS, you need an multiplexer tool, as gpsd or gypsy.
+* source="gpsd://host[:port]"	 - gpsd://localhost, the default one, will try to connect to gpsd on localhost
+* source="socket:ipaddr:post"    - socket connection (expects nmea stream)
+* source="socket:ipaddr:2947:r=1" - connect to gpsd in nmea mode (gpsd versions 2.39 or older)
+* source='socket:ipaddr:2947:?WATCH={"enable":true,"nmea":true};' - connect to gpsd in nmea mode (gpsd versions newer than 2.39)
+* source="gypsy://connectstring" - gypsy
+
+**Tricks:**
+* source="file:/home/myhome/mynmea.log" : here, navit will replay the nmea logfile (under Windows it is currently not possible in Navit)
+* source="pipe:/usr/bin/gpspipe -r" - any executable that produces NMEA output - gpsbabel, gpspipe, ...
+* source="demo://" : to use the demo vehicle. Set your Position and Destination, and vehicle will follow the calculated route. Useful if you have no nmea data source.
+* source="null://" : no GPS at all
+
+===Logging tracks===
+To record your trip , you can add a sub-instance "log" to the vehicle. It is possible to add multiple logs.
+
+
+.. code-block:: xml
+
+<source lang="xml">
+ <log type="gpx" data="track_%Y%m%d%i.gpx" flush_size="1048576" flush_time="900" />
+ <log type="nmea" data="track_%Y%m%d%i.nmea" flush_size="1048576" flush_time="900" />
+</source>
+
+
+This will give a log file named YearMonthDaySequencenumber.gpx/.nmea which will be kept in memory and flushed to disk when it is 1048576 bytes large or the oldest data is older than 900 seconds.
+<!--how to define, where the file get's stored?-->
+
+To display your track for more than one hour, you must use [[binfile]] to create a cache file that get's display <!--do I need to add it as a map source?-->
+
+.. code-block:: xml
+
+<source lang="xml">
+ <log type="binfile" data="track.bin" flush_size="0"/>
+</source>
+
+For customizing what is stored, see [[GPX]]
+
+===Vehicleprofile===
+[[Vehicleprofile | Profiles to add in the navit.xml]]
+<br/>
+<!-- this is tricky, here we need a step by step introduction-->
+Defines the behaviour of the routing and are usually linked to a vehicle section, so switching the "vehicle" (type of mobility) from within Navit, routing also will change its behaviour. This way, it is possible to include steps for pedestrian routing, but to exclude it for bike, horse or car routing. Within the vehicleprofile section, roadprofile sections are used to describe the routing behaviour of different roads. Here's a very basic example:
+
+
+.. code-block:: xml
+
+<source lang="xml">
+<vehicleprofile name="bike" flags="0x40000000" flags_forward_mask="0x40000000" flags_reverse_mask="0x40000000" maxspeed_handling="1" route_mode="0">
+  <roadprofile item_types="path,track_ground" speed="12" route_weight="5">
+  </roadprofile>
+  <roadprofile item_types="track_gravelled,track_paved,cycleway,street_service,street_parking_lane,street_0,street_1_city,living_street,street_2_city,street_1_land,street_2_land,street_3_city" speed="25" route_weight="15">
+  </roadprofile>
+  <roadprofile item_types="roundabout" speed="20" route_weight="10"/>
+  <roadprofile item_types="ferry" speed="40" route_weight="40"/>
+ </vehicleprofile>
+</source>
+
+For details on the flags, see [[Vehicle profile flags]].
+The speeds are in km/h.
+
+Only the vehicle profile names "car", "bike" and "pedestrian" are translated in the GUI.
+
+
+[[Category:Customizing]]
+[[Category:Configuration]]
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 000000000..dc9f0a6ff
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,40 @@
+Navit's User Manual
+===================
+
+This document is the official User Manual for `Navit`__,
+the OpenSource vector based navigation software.
+
+Navit is a open source (GPL) car navigation system with routing engine.
+
+It's modular design is capable of using vector maps of various formats for routing and rendering of the displayed map. It's even possible to use multiple maps at a time.
+
+The user interfaces are designed to work well with touch screen displays. Points of Interest of various formats are displayed on the map.
+
+The current vehicle position is either read from gpsd or directly from NMEA GPS sensors.
+
+The routing engine not only calculates an optimal route to your destination, but also generates directions and even speaks to you.
+
+Navit currently speaks over 70 languages!
+
+Navit is highly customizable, from map layouts and on-screen display to the details of the routing engine.
+
+.. image:: navit.png
+
+.. toctree::
+    :hidden:
+    :glob:
+    :numbered:
+    :maxdepth: 2
+
+    basic_configuration
+    maps
+
+
+.. Indices and tables
+.. ------------------
+
+.. * :ref:`genindex`
+.. * :ref:`modindex`
+.. * :ref:`search`
+
+.. __: https://github.com/navit-gps/navit/
diff --git a/docs/maps.rst b/docs/maps.rst
new file mode 100644
index 000000000..ff5b18c2f
--- /dev/null
+++ b/docs/maps.rst
@@ -0,0 +1,20 @@
+.. _maps:
+Maps
+====
+
+Navit can use a variety of maps from a number of sources. This includes free and commercial material, that can be read using different map drivers which allow different sets of functionality. The visual design of maps can be adjusted with a layout.
+
+The following matrix shows at-a-glance the features that each supported map type has.
+
+============================== ======== ===== ======= ====== == =============== ========
+Provider                       Coverage Age   Binfile Garmin mg poi_geodownload textfile
+============================== ======== ===== ======= ====== == =============== ========
+OpenStreetMap                  global   daily Yes     Yes
+Garmin maps                    global         Yes     Yes
+Marco Polo Grosser Reiseplaner EU       > 4y
+Routeplaner Europa 2007        EU       > 4y
+Map + Route                    EU       > 4y
+============================== ======== ===== ======= ====== == =============== ========
+
+.. include:: osm.rst
+.. include:: binfile.rst
diff --git a/docs/navit.png b/docs/navit.png
new file mode 100644
index 000000000..81f3239d6
--- /dev/null
+++ b/docs/navit.png
diff --git a/docs/osm.rst b/docs/osm.rst
new file mode 100644
index 000000000..12766d0d2
--- /dev/null
+++ b/docs/osm.rst
@@ -0,0 +1,117 @@
+.. _OpenStreetMap:
+OpenStreetMap
+-------------
+
+`OpenStreetMap <http://www.openstreetmap.org/>`_ is a free editable map of the whole world. It is made by people like you. OpenStreetMap allows you to view, edit and use geographical data in a collaborative way from anywhere on Earth. Maps from OpenStreetMap can be used in Navit.
+
+Quick Start
+~~~~~~~~~~~
+
+* Go to `Navit Planet Extractor <http://maps.navit-project.org/>`_
+* Zoom in and select the area that you are interested in. Use the 'Map Controls' on the right to switch between 'Navigation' and 'Select' modes. or use preselected areas:
+ * `Germany <http://maps.navit-project.org/api/map/?bbox=5.185546875,46.845703125,15.46875,55.634765625>`_
+ * `France <http://maps.navit-project.org/api/map/?bbox=-5.44921875,42.01171875,8.437500000000002,51.6796875>`_
+ * `BeNeLux <http://maps.navit-project.org/api/map/?bbox=2.08740234375,48.8671875,7.778320312500001,54.51416015625>`_
+ * `Spain/Portugal <http://maps.navit-project.org/api/map/?bbox=-11.0302734375,34.87060546875,4.614257812500003,44.40673828125>`_
+ * `Italy <http://maps.navit-project.org/api/map/?bbox=6.52587890625,36.38671875,18.96240234375,47.197265625>`_
+ * `Entire planet <http://maps.navit-project.org/planet.bin>`_
+* Hit '''Get Map!'''
+* Move the downloaded map to the directory of your choice, and add it to the active the mapset (see [[Configuration]]) in navit.xml with a line similar to the following:
+
+.. code-block:: xml
+
+ <mapset>
+  <map type="binfile" enabled="yes" data="/path/to/your/map/osm_bbox.bin" />
+ </mapset>
+
+Add OSM map to your mapset
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Move the downloaded map to the directory of your choice, and add it to the active mapset (see [[Configuration]]) in navit.xml with a line similar to the following:
+
+.. code-block:: xml
+
+ <mapset>
+  <map type="binfile" enabled="yes" data="/path/to/your/map/my_downloaded_map.bin" />
+ </mapset>
+
+Topographic Maps
+~~~~~~~~~~~~~~~~
+Navit will display elevation/height lines but the required data is not included in most OSM derived maps.
+
+Navit compatible maps with height lines can be created by feeding the output of `Phyghtmap <http://wiki.openstreetmap.org/wiki/Phyghtmap>`_ to Navit's maptool. Alternatively the SRTM data can be downloaded in osm.xml format http://geoweb.hft-stuttgart.de/SRTM/srtm_as_osm/, avoiding the Phygtmap step. The information can be either merged with OSM derived maps or used in a separate layer.
+
+Many Garmin type maps such as http://www.wanderreitkarte.de/garmin_de.php also have the height lines information but routing will not work with them.
+
+Processing OSM Maps yourself
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+You can create your own Navit binfiles from OSM data very easily using [[maptool]], the conversion program which installs alongside Navit. ''maptool'' can process both OpenStreetMap XML Data files (*.osm files) and OpenStreetMap Protobuf Data files (*.pbf files) Follow these steps to process your own maps.
+
+Download your own OSM data
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+OSM data can be downloaded from a variety of sources. OpenStreetMap XML Data files are regular textfiles, easily editable in any text editor. OpenStreetMap Protobuf Data files are binary files, which take up less space (so are quicker to download and process) but are not editable.
+
+* '''OpenStreetMap XML Data'''
+ * `Geofabrik <http://download.geofabrik.de/osm/>`_ provides pre-processed OpenStreetMap XML Data files of almost all countries, and all continents. This method is probably the easiest way of downloading OpenStreetMap XML Data for an entire country or continent. Note that the OSM files are bzipped
+ * `planet.openstreetmap.org <http://planet.openstreetmap.org>`_ hosts the complete data set (the whole world). You can use `Osmosis <http://wiki.openstreetmap.org/index.php/Osmosis>`_ to cut it into smaller chunks.
+ * `OpenStreetMap ReadOnly (XAPI) <http://wiki.openstreetmap.org/wiki/Xapi>`_ The API allows to get the data of a specific bounding box, so that download managers can be used. For example:
+ wget -O map.osm "http://xapi.openstreetmap.org/api/0.6/map?bbox=11.4,48.7,11.6,48.9"
+ * [http://www.openstreetmap.org/export OpenStreetMap (visual)] allows you to select a small rectangular area and download the selection as OpenStreetMap XML Data.
+* '''OpenStreetMap Protobuf Data'''
+ * [http://download.geofabrik.de/osm/ Geofabrik] provides pre-processed OpenStreetMap Protobuf Data files of almost all countries, and all continents.
+
+Convert OSM data to Navit binfile
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+The following examples assume that you have installed Navit system-wide. If this is not the case, you will need to provide an absolute path to the ''maptool'' executable, which is in the navit/maptool folder.
+
+Please also note, that maptool uses country multipolygon relations. So it's a good idea to include the whole country boundary to your dataset. You can use the josm editor to download the country boundary relation and save it as osm file. Then this file can be concatenated with your sub-country level excerpt.
+
+From .osm
+"""""""""
+.. code-block:: bash
+
+  cat my_OSM_map.osm | maptool my_Navit_map.bin
+
+Or
+
+.. code-block:: bash
+
+  maptool -i my_OSM_map.osm my_Navit_map.bin
+
+Or for multiple OSM data files use the <tt>--dedupe-ways</tt> option to avoid duplication of way data if a way occurs multiple times in the OSM maps.
+
+.. code-block:: bash
+
+ cat my_OSM_map1.osm my_OSM_map2.osm my_OSM_map3.osm | maptool --dedupe-ways my_Navit_map.bin
+
+From .bz2
+"""""""""
+.. code-block:: bash
+
+  bzcat my_OSM_map.osm.bz2 | maptool my_Navit_map.bin
+
+From .pbf
+"""""""""
+.. code-block:: bash
+
+ maptool --protobuf -i my_OSM_map.osm.pbf my_Navit_map.bin
+
+Processing the whole Planet
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The OpenStreetMap wiki [http://wiki.openstreetmap.org/index.php/Planet.osm Planet.osm] page lists mirrors where Planet.osm can be downloaded. There are also downloads of smaller areas such as the UK and parts of Europe. These smaller excerpts are a lot quicker to download and process.
+
+In case you want the whole planet.osm (24GB in December 2012), it is even possible to process planet.osm. It will take about 7 hours , requires > 1GB of main memory and about 30 GB disk space for result and temp files - planet.bin is currently (as of December 2012) 9.6GB:
+
+.. code-block:: bash
+
+ bzcat planet.osm.bz2 | maptool -6 my_Navit_map.bin
+
+Please note -6 option (long name --64bit) used above. It should be used always if output bin file grows above 4GB, or generated file will not work at all. Using that option on smaller files slightly increases their size and makes them unreadable by some unzip versions.
+
+Tips
+~~~~
+* To enable a map you have downloaded refer [[OpenStreetMap#Adding_an_OSM_map_to_your_mapset| adding OSM map to navit.xml]]
+* If you don't see any map data in Navit (assuming your map is properly specified in navit.xml) using the Internal GUI click anywhere on the screen to bring up the menu. Click on "Actions" and then "Town". Type in the name of a town that should be within your map data. Select your town from the list that appears. This will bring up a sub-menu where you can click "View On Map". Note that if you have a GPS receiver you can also just wait till you get a satellite lock.
+* To avoid changing navit.xml if you update your maps and the maps have different file names use the wildcard (\*.bin) in your navit.xml file. For example:
+.. code-block:: xml
+
+ <map type="binfile" enabled="yes" data="/media/mmc2/maps/*.bin"/>