From 838fefba8bdfa46ad21bca64d017ba05ff3f6d97 Mon Sep 17 00:00:00 2001
From: Pieter Vander Vennet <pietervdvn@posteo.net>
Date: Mon, 17 Oct 2022 16:02:34 +0200
Subject: [PATCH] Improve documentation, output some general intro in the
helptext
---
AspectedRouting/AspectedRouting.csproj | 3 ++
{Examples => AspectedRouting}/Format.md | 48 ++++++++++++++-----------
AspectedRouting/IO/MdPrinter.cs | 3 +-
3 files changed, 33 insertions(+), 21 deletions(-)
rename {Examples => AspectedRouting}/Format.md (87%)
diff --git a/AspectedRouting/AspectedRouting.csproj b/AspectedRouting/AspectedRouting.csproj
index f224198..3d8420c 100644
--- a/AspectedRouting/AspectedRouting.csproj
+++ b/AspectedRouting/AspectedRouting.csproj
@@ -15,6 +15,9 @@
<None Update="Examples\**">
<CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
</None>
+ <None Update="Format.md">
+ <CopyToOutputDirectory>PreserveNewest</CopyToOutputDirectory>
+ </None>
</ItemGroup>
</Project>
diff --git a/Examples/Format.md b/AspectedRouting/Format.md
similarity index 87%
rename from Examples/Format.md
rename to AspectedRouting/Format.md
index b2e5dee..176c9fb 100644
--- a/Examples/Format.md
+++ b/AspectedRouting/Format.md
@@ -1,23 +1,13 @@
+# Building a profile
-# Functions
-
-- `$funcName` indicates a builtin function
-- `#parameter` indicates a configurable parameter
-
-A profile is a function which maps a set of tags onto a value. It is basically Haskell, except that functions can have _multiple_ types. During typechecking, some types will turn out not to be possible and they will dissappear, potentially fixing the implementation of the function itself.
-
-# Injected tags
-
-Aspects can use the following (extra) tags:
-
-- `_direction` is the value to indicate if the traveller goes forward or backwards. It is not available when calculating the 'oneway' field
-- `access` will become the value calculated in the field `access` (not available to calculate access)
-- `oneway` will become the value calculated in the field `oneway` (not available to calculate access and speed)
+A profile is a .json-file, which consists of a few metadatafields (which are simple strings),
+some expressions to calculate values based on tags, a list of parameters with their default values and
+a list of profiles containing the actual parameter value for that profile.
# Vehicle.json
-- Metdata: these tags will be copied to the routerdb, but can not be used for routeplanning. A prime example is `name` (the streetname), as it is useful for routeplanning but very useful for navigation afterwards
+- Metadata: these tags will be copied to the routerdb, but can not be used for routeplanning. A prime example is `name` (the streetname), as it is useful for routeplanning but very useful for navigation afterwards
- vehicletypes: used for turn restrictions, legacy for use with itinero 1.0
- defaults: a dictionary of `{"#paramName": "value"}`, used in determining the weight of an edge. note: the `#` has to be included
- `access` is a field in the vehicle file. It should be an expression returning a string. If (and only if) this string is `no`, the way will be marked as not accessible and no more values will be calculated. All other values are regarded as being accessible. When calculated, the tag `access` with the calculated value is written into the tag table for the other aspects to use.
@@ -27,11 +17,7 @@ Aspects can use the following (extra) tags:
- `obstacleaccess` and `obstaclecost` are two (optional) expressions that calculate whether an obstacle can be passed and if so, if there is a penalty for this. See detailed explanations below
- `priorities`: a table of `{'#paramName', expression}` determining the priority (1/cost) of a way, per meter. The formula used is `paramName * expression + paramName0 * expression0 + ...` (`speed`, `access` and `oneway` can be used here as tags indicate the earlier defined respective aspects). Use a weight == 1 to get the shortest route or `$speed` to get the fastest route
-
-## Why is `access`, `oneway` and `speed` copied onto the tags?
-
-`speed` is copied in order for the profile to be able to make a `fast` profile (and accessible as `$speed`).
-Access is copied so that `highway=cycleway` and `highway=cycleway;bicycle=designated` will render the same result.
+- `scalingfactor` works in tandem with priority. The _total_ resistance of a link is `priority * scalingfactor`. If this function returns `null`, this will be defaulted to 1.
# Calculating oneway and forward/backward speeds
@@ -63,6 +49,28 @@ If `obstacleaccess` is not `no` or `false`, then `obstaclecost` will be triggere
If the resulting cost is null, the default implementation will be used.
+# Functions
+
+- `$funcName` indicates a builtin function
+- `#parameter` indicates a configurable parameter
+
+A profile is a function which maps a set of tags onto a value. It is basically Haskell, except that functions can have _multiple_ types. During typechecking, some types will turn out not to be possible and they will dissappear, potentially fixing the implementation of the function itself.
+
+# Injected tags
+
+Aspects can use the following (extra) tags:
+
+- `_direction` is the value to indicate if the traveller goes forward or backwards. It is not available when calculating the 'oneway' field
+- `access` will become the value calculated in the field `access` (not available to calculate access)
+- `oneway` will become the value calculated in the field `oneway` (not available to calculate access and speed)
+
+## Why is `access`, `oneway` and `speed` copied onto the tags?
+
+`speed` is copied in order for the profile to be able to make a `fast` profile (and accessible as `$speed`).
+Access is copied so that `highway=cycleway` and `highway=cycleway;bicycle=designated` will render the same result.
+
+
+
# Pitfalls
"$all" should not be used together with a mapping: it checks if all _present_ keys return true or yes (or some other value); it does _not_ check that all the specified keys in the mapping are present.
diff --git a/AspectedRouting/IO/MdPrinter.cs b/AspectedRouting/IO/MdPrinter.cs
index 65c9f10..5b49389 100644
--- a/AspectedRouting/IO/MdPrinter.cs
+++ b/AspectedRouting/IO/MdPrinter.cs
@@ -14,7 +14,8 @@ namespace AspectedRouting.IO
{
public static void GenerateHelpText(string saveTo = null)
{
- var helpText = TypeOverview +
+ var format = File.ReadAllText("Format.md");
+ var helpText =format +"\n\n" + TypeOverview +
FunctionOverview;
if (saveTo == null)