Readthedocs import

.circleci/config.yml

@@ -227,6 +227,29 @@ jobs:
       - run:
           name: Update results to Github
           command: export GIT_TERMINAL_PROMPT=0 && git push origin $CIRCLE_SHA1:refs/heads/master
+  check_spelling:
+    <<: *defaults
+    steps:
+      - checkout
+      - run:
+          name: Install curl
+          command: apt-get update && apt-get -y install curl
+      - run:
+          name: Install misspell
+          command: |
+              curl -L -o ./install-misspell.sh https://git.io/misspell
+              sh ./install-misspell.sh -b /usr/local/bin/
+      - run:
+          name: Check docs folder for misspells
+          command: |
+              misspell docs/ > typos.txt
+              if [[ $( wc -l < typos.txt ) -gt 0 ]]; then
+                echo "Typos/mispells found, please fix them";
+                cat typos.txt
+                exit -1
+              fi
+
+
 workflows:
   version: 2
   build_all:
@@ -275,3 +298,7 @@ workflows:
           filters:
             branches:
               only: /^trunk$/
+      - check_spelling:
+          filters:
+            branches:
+              only: /^readthedocs$/

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" />

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

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'

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``).