Restrucuture documentation to smaller parts

docs/developers/android_service.md

@@ -0,0 +1,10 @@
+---
+parent: Developers
+---
+
+# Android Service
+
+BRouter exposes an [Android
+Service](https://developer.android.com/guide/components/services) which can be
+used by other applications to calculate routes. See `IBRouterService.aidl` for
+the interface definition.

docs/developers/build_segments.md

@@ -1,5 +1,6 @@
 ---
 parent: Developers
+title: Build segment files
 ---
 
 Build your own segments files

docs/developers/http_server.md

@@ -0,0 +1,16 @@
+---
+parent: Developers
+title: HTTP server
+---
+
+# Run the BRouter HTTP server
+
+Helpers scripts are provided in `misc/scripts/standalone` to quickly spawn a
+BRouter HTTP server for various platforms.
+
+* Linux/Mac OS: `./misc/scripts/standalone/server.sh`
+* Windows (using Bash): `./misc/scripts/standalone/server.sh`
+* Windows (using CMD): `misc\scripts\standalone\server.cmd`
+
+The API endpoints exposed by this HTTP server are documented in the
+`ServerHandler.java`

docs/developers/index.md

@@ -22,24 +22,3 @@ variables in the first `global` context of the profiles files.
 An helper script is available in `misc/scripts/generate_profile_variants.sh`
 to help you quickly generate variants based on the default profiles, to create
 a default set of profiles covering most of the basic use cases.
-
-## Run the BRouter HTTP server
-
-Helpers scripts are provided in `misc/scripts/standalone` to quickly spawn a
-BRouter HTTP server for various platforms.
-
-* Linux/Mac OS: `./misc/scripts/standalone/server.sh`
-* Windows (using Bash): `./misc/scripts/standalone/server.sh`
-* Windows (using CMD): `misc\scripts\standalone\server.cmd`
-
-The API endpoints exposed by this HTTP server are documented in the
-[`brouter-server/src/main/java/btools/server/request/ServerHandler.java`](brouter-server/src/main/java/btools/server/request/ServerHandler.java)
-file.
-
-## Android Service
-
-BRouter exposes an [Android
-Service](https://developer.android.com/guide/components/services) which can be
-used by other applications to calculate routes. See
-[`brouter-routing-app/src/main/aidl/btools/routingapp/IBRouterService.aidl`](brouter-routing-app/src/main/aidl/btools/routingapp/IBRouterService.aidl)
-for the interface definition.

docs/features/elevation.md

@@ -2,7 +2,7 @@
 parent: Features
 ---
 
-## Elevation algorithm
+## Elevation awareness
 
 Elevation awareness is the most important issue in bike routing if not routing
 in a flat country. But in most routing software, elevation is either not handled

docs/features/offline.md

@@ -27,31 +27,3 @@ developers to implement simplifications into the routing algorithm that affect
 the quality of the routing results. BRouter always does it's best on the
 quality, but has a processing time that scales quadratic with distance, leading
 to a limit at about 150km in air-distance, which is enough for a bikers daytrip.
-
-### Installing the BETA Version of BRouter on an Android smartphone.
-
-Before trying the Android app, you should have a look one the [online
-version](/brouter-web) to see what it's doing.
-
-What you should also do before trying the BRouter Android app is to install, an
-get familiar with, one of the supported map-apps. This is either
-[OsmAnd](http://www.osmand.net), which is a full offline navigation solution on
-it's own, but especially it's a wonderful offline OSM map tool and is able to
-give spoken directions to routes calculated either internally or externally.
-Other options are [Locus](http://www.locusmap.eu/) or
-[OruxMaps](http://www.oruxmaps.com/index_en.html).
-
-The BRouter Android app assumes that at least one of OsmAnd, Locus or OruxMaps
-is installed - it will not work otherwise.
-
-If you are o.k. with all that, you can install the BRouter Android app from the
-[brouter_1_6_1.zip](../brouter_bin/brouter_1_6_1.zip) installation ZIP-file
-including the APK and read the [readme.txt](readme.txt) ( **READ ME !** ) for
-details on how to add routing data and navigation profiles to your installation
-and how the interfacing between BRouter and the supported map-tools works.
-
-Navigation profiles and the lookup-data are [here](profiles2) Routing data files
-per 5*5-degree square are [here](/brouter/segments4)
-
-(The Map-Snapshot date is about 2 days before the timestamp of the routing data
-files)

docs/features/vianogo.md

@@ -7,17 +7,10 @@ parent: Features
 BRouter can process via-points and nogo-areas, and [brouter-web](/brouter-web)
 offers on online interface to edit both of them.
 
-For offline use, nogo-areas can be defined as wayoints using a special naming
-convention. Handling of via-points during offline use depends on the mode of
-operation, see the README for details.
-
-NoGo-Areas are forbidden areas. In fact, these are areas, not points, with a
-default radius of 20m around the given point. Every way that is touching this
-disc of 20m radius is excluded by the routing algorithm. But the radius can also
-be specified: a waypoint `nogo` default to 20m radius, but `nogo100` defines a
-nogo area with 100m radius. Theres no limit in radius, so you can also exclude a
-whole geographic region with a single nogo-area.
-
 Nogo areas are useful if you encouter an obstacle that is not contained in the
 underlying map. But they can also be useful in planning alternative routes by
 excluding e.g. a certain bridge or ferry.
+
+For offline use, nogo-areas can be defined as wayoints using a special naming
+convention. Handling of via-points during offline use depends on the mode of
+operation, see the README for details.

docs/index.md

@@ -4,7 +4,7 @@ title: Home
 nav_order: 1
 ---
 
-## BRouter: Let's get serious about bike routing
+# BRouter: Let's get serious about bike routing
 
 There's a lot of routing software on the market, both free and commercial, both
 online and offline, both OSM and proprietary maps. However, when it comes to
@@ -20,17 +20,12 @@ result.
 Here's what makes BRouter unique:
 
 - It uses [freely configurable routing profiles](features/costfunctions.md)
-
 - It works [fully offline on any Android phone](features/offline.md) and is
   interfaced to some of the most popular Android map tools
-
 - It uses a sophisticated [routing-algorithm](developers/algorithm.md) with
   [elevation consideration](features/elevation.md)
-
 - It offers [alternative route calculations](features/alternatives.md)
-
 - It supports [via and nogo-points](features/vianogo.md)
-
 - It can [consider long distance cycle routes](features/cycleroutes.md)
 
 Routing data is available worldwide with automatic weekly updates
@@ -49,7 +44,7 @@ if you want to use BRouter online.
 
 ### Android app for offline routing
 
-See [offline routing app](features/offline.md) for how to setup BRouter for
+See [Android quickstart guide](users/android_quickstart.md) for how to setup BRouter for
 offline routing on an Android smartphone.
 
 ### Revision history

docs/users/android_advanced.md

@@ -0,0 +1,146 @@
+---
+parent: Using BRouter
+nav_order: 2
+---
+
+# Android advanced configuration
+
+### Directory structure
+
+BRouter uses several subdirectories inside the base directory.
+
+| directory                         | description                                  |
+| --------------------------------- | -------------------------------------------- |
+| `<basedir>/brouter`               |                                              |
+| `<basedir>/brouter/modes`         | routing-mode/profile mapping and route cache |
+| `<basedir>/brouter/profiles2`     | lookup-table and routing-profiles (\*.brf)   |
+| `<basedir>/brouter/segments4`     | **routing data files (\*.rd5)**              |
+| `<basedir>/brouter/import`        | allow a small file exchange with other apps  |
+| `<basedir>/brouter/import/tracks` | place the `nogo*.gpx` files here             |
+
+`modes` contains `serviceconfig.dat` which defines _routing-mode_ /
+_routing-profile_ mapping and cached route results which are used for
+recalculations.
+
+`profiles2` contains `lookup.dat` (OSM tag access), `serverconfig.txt` and
+_routing-profiles_.
+
+`segments4` contains `storageconfig.txt` and routing data files (\*.rd5). You
+can download them using the _Download Manager_ or as described in [Download
+Routing Segments](users/download_segments.md).
+
+### Configuration files
+
+#### serverconfig.txt
+
+`serverconfig.txt` is used to configure download information for routing
+profiles and routing segments.
+
+#### serviceconfig.dat
+
+`serviceconfig.dat` is used to configure mapping between _routing-mode_ and
+_routing-profile_.
+
+#### storageconfig.txt
+
+`storageconfig.txt` is used to specifiy additional paths which BRouter should
+use.
+
+* `secondary_segment_dir` points to an additional directory containing routing
+  data files. This can be located anywhere.
+
+  When searching for datafiles, both the download manager and the router first
+  look in the primary (brouter/segments4) and then in the secondary directory.
+  On the other hand, the download manager always writes new datafiles to the
+  primary directory, so the secondary directory is read-only.
+
+  You can move datafiles downloaded by the download-manager to the secondary
+  directory, by using a file manager, in order to free disk space on the
+  internal card.
+
+* `additional_maptool_dir` points to a directory that should be scanned for
+  maptool-installations in addition to the standard-guesses.
+
+#### Redirect files
+
+When using the _file interface_ with waypoints from other app's storage BRouter
+tries to write the calculated tracks to the app storage. Depending on the
+Android version this won't work. BRouter can be configured to write tracks to a
+different directory by creating a `brouter.redirect` file which contains a
+single line with the absolute path to the folder where the tracks should be
+written.
+
+* For LocusMap `brouter.redirect` has to be located in `Locus/mapItems`
+* For OruxMaps `brouter.redirect` has to be located in `oruxmaps/tracklogs`
+* For OsmAnd `brouter.redirect` has to be located in `osmand/tracks`
+
+## Using nogo-areas
+
+There's a special naming-convention to specify nogo-areas:
+
+`nogo[radius] [name]` defines a nogo-area, where radius (in Meter) is optional
+and defaults to 20m, and the name is also optional. So `nogo`, `nogo1000`, `nogo
+roadblock`, `nogo200 badferry` are all valid names for nogo-waypoints.
+
+The effect is that BRouter searches a route that avoids the area defined by the
+position and the radius of the nogo-area.
+
+Nogo-areas are used when routing via _service interface_ and _file interface_.
+
+When using the _file interface_ you will get a nogo-dialog allowing to de-select
+them if nogo-waypoints are found in the waypoint-database. This de-selection can
+also be bound to a service mode using the _Server Mode_ button to make it
+effective using the _service interface_ as well, but initially, every nogo-area
+is effective in the _service interface_.
+
+Nogo-areas can be used either to account for real obstacles or to enforce
+personal routing preferences.
+
+## Routing via _file interface_
+
+The other option is using the BRouter app to calculate a route. This is the
+prefered option when calculating long-distance-routes that would not finish
+within the 60 seconds timout if calculated via the _service interface_.
+
+To do this, start the BRouter app, select two or more waypoints and then start
+the route calculation. BRouter either reads waypoints from the `import` folder
+or tries to read waypoints from other map tools if it has the required
+permission. These waypoints are called _Favorites_ in OsmAnd, _POIs_ in Locus or
+_Waypoints_ in Oruxmaps and allow to associate a location with a name.
+
+If your waypoint database contains a `from` and `to` waypoint the waypoint
+selection will be skipped. BRouter also uses `via1`, ..., `via9` as via
+waypoints.
+
+If a route is calculated, it is stored as `brouter0.gpx`. Depending on the
+waypoint database and permissions BRouter stores the route in
+`<basedir>/import/tracks` or in the map tool track directory. If started once
+more with identical input, BRouter will store a second route broute1.gpx for the
+first alternative and so on.
+
+### Permission issues
+
+If using the file interface BRouter needs to access the files from other apps.
+Depending on your android version, your BRouter version and location of other
+apps locations it will be impossible to read or write those files.
+
+## Mixed operation: _timeout-free recalculations_
+
+You can combine both operation modes (_service interface_ + _file interface_ to
+become able to calculate very long distances, but make use of the advantages of
+the service interface as well, especially the dynamic recalculations if you get
+off the track, without running into the 60 seconds timeout.
+
+To support this, BRouter can do _timeout free recalculations_. It works by
+initially calculating a track to your destination and binding it to one or more
+routing-modes using the _Server Mode_ button. This way, BRouter stores a
+_reference track_ in the `brouter/modes` subdirectory.
+
+If afterwards a route to the exact same destination is calculated via the
+service interface, BRouter uses a special calculation mode that makes use of the
+reference track for faster processing that is guaranteed to give a result within
+60 seconds. _Exact same_ destination means withing 5m, so best use the same
+waypoint for re-calculating that you used for the initial calculation.
+
+This way you can follow a long distance route via the _service interface_,
+enjoying automatic recalculations if you get off the track.

docs/users/android_quickstart.md

@@ -0,0 +1,92 @@
+---
+parent: Using BRouter
+nav_order: 1
+---
+
+# Android quickstart guide
+
+### Choosing and installing a map tool
+
+BRouter just calculates tracks as GPX or GeoJSON files. It does not display maps
+or give any navigation instuctions. Therefore you need a map-tool in order for
+BRouter to be useful.
+
+Several map tools support routing with BRouter:
+
+- [_OsmAnd_](http://www.osmand.net): GPLv3, Free (limited features) and paid version available
+- [_Locus Map_](http://www.locusmap.eu): Proprietary, Free (ads) and paid version available
+- [_Oruxmaps_](http://www.oruxmaps.com): Proprietary, Free (previous version) and paid version available
+
+Install any of those map tools using your favorite app store.
+
+### Installing BRouter
+
+You can install BRouter either from
+[F-Droid](https://f-droid.org/packages/btools.routingapp), [Google Play
+Store](https://play.google.com/store/apps/details?id=btools.routingapp) or from
+the APK contained in the releases available in the [Revision
+History](https://brouter.de/brouter/revisions.html).
+
+### Choosing a base directory
+
+When first starting BRouter (or after deleting/moving the base directory), it
+asks for a directory and gives you proposals plus the option to enter any other
+base directory.
+
+Most phones have an internal and an external storage, where the external storage
+is a SD card which can be removed from the device.
+
+Navigation needs big data files that usually should go on an external storage
+because it provides larger capacity. You should accept the external storage,
+which is usually the one with the most space available.
+
+Since Android 11 apps can only write to their app-specific storage so BRouter
+can only use `<...>/Android/media/btools.routingapp/` as base directory. The
+app-specific storage can be located on internal or external storage.
+
+On Android versions prior to 11 it is possible to read and write to other
+locations which is used for the _file interface_. For the _service interface_
+access to other apps app-specific storage isn't required.
+
+### Download routing segments
+
+BRouter requires routing data which is independent of the displayed map of a map
+tool. Routing segments (`rd5`) can be downloaded using the BRouter _Download
+Manager_.
+
+## Routing via _service interface_
+
+BRouter is best used via it's _service interface_. It provides a service which
+can be used by map tools without starting the BRouter app.
+
+To use BRouter in your map tool you have to configure the map tool to use
+BRouter as navigation service.
+
+- [Instructions for LocusMap](https://docs.locusmap.eu/doku.php?id=manual:faq:how_to_navigate_offline)
+- [Instructions for OsmAnd](https://osmand.net/features/navigation-profiles#create_brouter)
+
+  Note: OsmAnd only displays BRouter as navigation service if BRouter is
+  installed. You have to install BRouter before configuring OsmAnd.
+
+The _service interface_ allows specifing either a _routing-mode_ (used by OsmAnd
+and OruxMaps) or a _routing-profile_ (used by LocusMap). When using a
+_routing-mode_ BRouter selects the _routing-profile_ according to a mapping.
+
+By default BRouter uses the following mapping:
+
+| routing-mode   | routing-profile |
+| -------------- | --------------- |
+| motorcar_fast  | car-test        |
+| motorcar_short | moped           |
+| bicycle_fast   | fastbike        |
+| bicycle_short  | trekking        |
+| foot_fast      | shortest        |
+| foot_short     | shortest        |
+
+This mapping, however, can be changed any time by starting the BRouter and using
+the _Server Mode_.
+
+If your routing request fails due to timeout you can open BRouter and select
+_Server Mode_ and recalculate the route using _\<repeat:...\>_. BRouter caches
+the routing result and further requests using the _same_ destination using the
+_service interface_ will be successful.

docs/users/download_segments.md

@@ -0,0 +1,23 @@
+---
+parent: Using BRouter
+---
+
+# Download Routing Segments
+
+Routing data files are organised as 5\*5 degree files, with the filename
+containing the south-west corner of the square, which means:
+
+- You want to route near West48/North37 -> you need `W50_N35.rd5`
+- You want to route near East7/North47 -> you need `E5_N45.rd5`
+
+These data files, called _segments_ across BRouter, are generated from
+[OpenStreetMap](https://www.openstreetmap.org/) data and stored in a custom
+binary format (rd5) for improved efficiency of BRouter routing.
+
+## Download them from brouter.de
+
+Segments files from the whole planet are generated weekly at
+[https://brouter.de/brouter/segments4/](http://brouter.de/brouter/segments4/).
+
+You can download one or more segments files, covering the area of the planet
+your want to route, into the `segments4` directory.

docs/users/index.md

@@ -1,8 +1,10 @@
 ---
-title: Using BRouter
+has_children: true
 nav_order: 3
 ---
 
+# Using BRouter
+
 ## Online
 
 Check [brouter-web](https://brouter.de/brouter-web/) or
@@ -10,30 +12,8 @@ Check [brouter-web](https://brouter.de/brouter-web/) or
 
 ## BRouter on Android
 
-You can install the BRouter app on your Android device from
+BRouter provides offline route calculation on Android. To get started with
-[F-Droid](https://f-droid.org/packages/btools.routingapp) or [Google Play
+BRouter on Android see the [Quickstart](android_quickstart.md).
-Store](https://play.google.com/store/apps/details?id=btools.routingapp). Older
-versions are available in the [revision history](../revisions.md). You can find
-detailed documentation of the BRouter Android app in
-[`misc/readmes/readme.txt`](misc/readmes/readme.txt).
-
-### Android with Locus
-
-You can use BRouter as the offline routing engine for [Locus
-Map](https://www.locusmap.eu/) on your Android device. This is currently the
-most featureful and maintained solutions for using BRouter on your Android
-device.
-
-A full documentation on how to set this up is available in the [LocusMap user
-manual](https://docs.locusmap.eu/doku.php?id=manual:faq:how_to_navigate_offline).
-
-### Android with OsmAnd
-
-Alternatively, you can also use BRouter as the offline routing engine for
-[OsmAnd](https://osmand.net/) on your Android device.
-
-A full documentation on how to set this up is available in the [OsmAnd feature
-description](https://osmand.net/features/navigation-profiles#create_brouter).
 
 ## Google group for support questions and feedback