Merge pull request #195 from ThomasWaldmann/fix-typos

profile developers guide: fix typos and whitespace

misc/readmes/profile_developers_guide.txt

@@ -15,14 +15,14 @@ that are considered for encoding.
 
 For each tag there are 2 special values:
 
-- <empty> if the tag is not set or the value is empty 
+- <empty> if the tag is not set or the value is empty
 - "unknown" if the value is not contained in the table
 
 Each value can have optional "aliases", these alias
 values are encoded into the same binary value as the
 associated primary value.
 
-A profile must use expression the primary value, as
+A profile must use the primary value in expressions, as
 aliases trigger a parse error.  E.g. if there is a line
 in lookups.dat file:
 
@@ -33,9 +33,10 @@ gives an error.
 
 The numbers in the lookup table are statistical
 information on the frequency of the values in the
-map of germany - these are just informational and
+map of Germany - these are just informational and
 are not processed by BRouter.
 
+
 Context-Separation
 ------------------
 
@@ -48,13 +49,13 @@ mark the beginning of each section.
 An exception from context separation is the node-context,
 where variables from the way-context of the originating
 way can be accessed using the "way:" prefix. For the
-variable nodeaccessgranted there's an additonal
+variable nodeaccessgranted there's an additional
-legacy-hack to access it as a loohup value without prefix:
+legacy-hack to access it as a lookup value without prefix:
 
-  if nodeaccessgranted=yes then ... 
+  if nodeaccessgranted=yes then ...
+
+while in the general case the prefixed expressions are variables:
 
-while in the genreal case the prefixed expressions are variables:
-  
   if greater way:costfactor 5 then ...
 
 In the profile scripts there is a third context "global"
@@ -65,6 +66,7 @@ The variables from the "global" section in the profile
 scripts are read-only visible in the "way" and
 "node" sections of the scripts.
 
+
 Predefined variables in the profile scripts
 -------------------------------------------
 
@@ -103,7 +105,7 @@ the routing engine:
    - turnInstructionRoundabouts     default=true=generate explicit roundabout hints
 
   - variables to modify BRouter behaviour
-  
+
    - processUnusedTags  ( default is false )
          If an OSM tag is unused within the profile,
          BRouter totally ignores the tag existence.
@@ -128,24 +130,25 @@ the routing engine:
 
   - initialcost
 
+
 The operators of the profile scripts
 ------------------------------------
 
-The profile scripts use polnic notation (=operator first)
+The profile scripts use polish notation (operator first).
 
 The "assign" operator is special: it can be used
-only on the top level of the expression hirarchy
+only on the top level of the expression hierarchy
 and has 2 operands:
 
   assign <variable-name> <expression>
 
 It just assigns the expression value to this
-variable (which can be a predined variable or
+variable (which can be a predefined variable or
 any other variable, which in this case is defined
 implicitly). The expression can be a complex expression
 using other operators.
 
-All other operators can be used recursively to an unlimted
+All other operators can be used recursively to an unlimited
 complexity, which means that each operand can be a composed
 expression starting with an operator and so on.
 
@@ -158,12 +161,12 @@ All expressions have one of the following basic forms:
   - <3-op-operator> <operand> <operand> <operand>
 
 - A numeric value is just a number, floating point, with "." as
-  decimal separtor. Boolean values are treated as numbers as well,
+  decimal separator. Boolean values are treated as numbers as well,
   with "0" = false and every nonzero value = true.
 
 - A lookup match has the form <tag-name>=<value>, e.g. highway=primary
   Only the primary values can be used in lookup-matches, not aliases.
-  The <empty> value is refered to as an empty string, e.g. access=
+  The <empty> value is referred to as an empty string, e.g. access=
 
 - 1 Operand operators are:
 
@@ -189,13 +192,13 @@ All expressions have one of the following basic forms:
 
   So the switch expression has a numeric value which is the
   true-expression if the boolean expression is true, the
-  false-expression otherwise
+  false-expression otherwise.
 
 
 Syntactic Sugar
 ---------------
 
-To improve the readablity of the profile-scripts, some syntactic variations
+To improve the readablity of the profile scripts, some syntactic variations
 are possible:
 
 - "if then else" : "if" can be used instead of the "switch" operator, if the
@@ -204,7 +207,7 @@ are possible:
   if <boolean-expression> then <true-expression> else <false-expression>
 
 - Parentheses: each expression can be surrounded by parentheses: ( <expression> )
-  Please note that the profile syntax, due to the polnic notation, does not
+  Please note that the profile syntax, due to the polish notation, does not
   need parentheses, they are always optional. However, if there are parentheses,
   the parser checks if they really match the expression boundaries.
 
@@ -212,13 +215,13 @@ are possible:
   lookup matches where more than one value is accepted for a key:
   highway=primary|secondary|tertiary
 
-- additional "=" symbol for "assign"operations:
+- additional "=" symbol for "assign" operations:
   assign <variable-name> = <expression>
 
 - boolean constants: "true" and "false" can be used instead of 1 and 0
 
-Please note the the tokenizer always expects blank space to separate
+Please note that the tokenizer always expects blank space to separate
-symbols and expressions so it is not allowed to places parentheses or
+symbols and expressions so it is not allowed to place parentheses or
 the "=" symbol without separating blank space!
 
 
@@ -227,48 +230,50 @@ The initial cost classifier
 
 To trigger the addition of the "initialcost", another variable is used:
 "initialclassifier" - any change in the value of that variable leads
-to adding the value of "initialcost". 
+to adding the value of "initialcost".
 
-Initial cost is used typically for ferry, where you want to apply
+Initial cost is used typically for a ferry, where you want to apply
-a penalty independent of the lenght of the ferry line
+a penalty independent of the length of the ferry line.
 
-Another useful case may be an initial cost for bicycle mounting/dismounting, 
+Another useful case may be an initial cost for bicycle mounting/dismounting,
 having set an initialclassifier for ways without bicycle access, with high initialcost.
-For backward compatibility, if "initialclassifier"  = 0, it is replaced
+For backward compatibility, if "initialclassifier" = 0, it is replaced
 by the costfactor.
 
+
 The priority classifier
 -----------------------
 
 Priorityclassifier is a BRouter numerical parameter
-calculated for ways and used for generation of pictogram/voice navigation instructions. 
+calculated for ways and used for generation of pictogram/voice navigation instructions.
 
-Higher values means the more significant(noticeable) way,
+Higher values means the more significant (noticeable) way,
-AFA it can be predicted from OSM data. 
+as far as it can be predicted from OSM data.
 
-To avoid navigation instruction flood, it was decided 
+To avoid a navigation instruction flood, it was decided
-the instructions are provided only if:
+that the instructions are provided only if:
 
-1/ You are supposed to turn at a crossroad/junction 
+1/ You are supposed to turn at a crossroad/junction
-    and some other ways have the same or higher Priorityclassifier value.
+    and some other ways having the same or higher Priorityclassifier value.
 OR
 2/ You are supposed to go straight ahead
-    and some other ways have the higher Priorityclassifier value.
+    and some other ways having the higher Priorityclassifier value.
 
 
 The elevation buffer ( From Poutnik's glossary )
--------------------
+------------------------------------------------
-with related 3 internal BRouter variables:
+
+With related 3 internal BRouter variables:
     - elevationpenaltybuffer
     - elevationmaxbuffer
     - elevationbufferreduce
 
-the Elevation Buffer is BRouter feature to filter elevation noise along the route. 
+the Elevation Buffer is BRouter feature to filter elevation noise along the route.
 It may be real, or caused by the artefacts of used SRTM elevation data.
 
 From every elevation change is at the first place cut out amount 10*up/downhillcutoff
-per every km of the way length. What remains, starts to accumulate in the buffer. 
+per every km of the way length. What remains, starts to accumulate in the buffer.
-IF cutoff demand of elevation per length is not saturated from incoming elevation, 
+IF cutoff demand of elevation per length is not saturated from incoming elevation,
 it is applied on elevation remaining in the buffer as well.
 
 E.g. if the way climbs 20 m along 500 m, and uphillcutoff=3.0, then 10*3.0*0.5 = 15 m
@@ -276,54 +281,53 @@ is taken away and only remaining 5 m accumulates. But if it climbed only 10 m
 on those 500m, all 10 m would be "swallowed" by cutoff,
 together with up to 5 m from the buffer, if there were any.
 
-When elevation does not fit the buffer of size elevationmaxbuffer, 
+When elevation does not fit the buffer of size elevationmaxbuffer,
-it is converted by up/downhillcost ratio to Elevationcost portion of Equivalentlength. 
+it is converted by up/downhillcost ratio to Elevationcost portion of Equivalentlength.
 Up/downhillcostfactors are used, if defined, otherwise CostFactor is used.
 
 elevationpenaltybuffer is BRouter variable, with default value 5(m).
    The variable value is used for 2 purposes:
    With the buffer content > elevationpenaltybuffer, it starts partially convert
-   the buffered elevation to ElevationCost by Up/downhillcost, with elevation taken 
+   the buffered elevation to ElevationCost by Up/downhillcost, with elevation taken
         = MIN (Buffer - elevationpenaltybuffer, WayLength[km] * elevationbufferreduce*10
    The Up/downhillcost factor takes place instead of costfactor at the percentage of
    how much is WayLength[km] * elevationbufferreduce*10 is saturated
    by the buffer content above elevationpenaltybuffer.
-        
+
 elevationmaxbuffer - default 10(m) - is the size of the buffer, above which
-   all elevation is converted to Elevationcost by Up/Downhillcost ratio, 
+   all elevation is converted to Elevationcost by Up/Downhillcost ratio,
    and - if defined - Up/downhillcostfactor fully replaces Costfactor
    in way cost calculation.
-    
+
 elevationbufferreduce - default 0(slope%)- is rate of conversion of the buffer content
-   above elevationpenaltybuffer to ElevationCost. For a way of length L, 
+   above elevationpenaltybuffer to ElevationCost. For a way of length L,
-   the amount of converted elevation is L[km] *elevationbufferreduce[%]*10. 
+   the amount of converted elevation is L[km] * elevationbufferreduce[%] * 10.
    The elevation to Elevationcost conversion ratio is given by Up/downhillcost.
-    
-Example: 
-   Let examine steady slopes with elevationmaxbuffer=10, elevationpenaltybuffer=5, 
-   elevationbufferreduce=0.5, cutoffs=1.5, Up/downhillcosts=60
 
-   All slopes within 0 .. 1.5% are swallowed by the cutoff
+Example:
+   Let's examine steady slopes with elevationmaxbuffer=10, elevationpenaltybuffer=5,
+   elevationbufferreduce=0.5, cutoffs=1.5, Up/downhillcosts=60.
 
-   For slope 1.75%, there will remain 0.25%. 
+   All slopes within 0 .. 1.5% are swallowed by the cutoff.
+
+   For slope 1.75%, there will remain 0.25%.
        That saturates the elevationbufferreduce 0.5% by 50%. That gives Way cost
-       to be calculated 50% from costfactor and 50% from Up/downhillcostfactor. 
+       to be calculated 50% from costfactor and 50% from Up/downhillcostfactor.
-       Additionally, 0.25% gives 2.5 m per 1km, converted to 2.5*60 = 150m of Elevationcost.
+       Additionally, 0.25% gives 2.5m per 1km, converted to 2.5*60 = 150m of Elevationcost.
 
    For slope 2.0%, there will remain 0.5%.
        That saturates the elevationbufferreduce 0.5% by 100%. That gives Way cost
-       to be calculated fully from Up/downhillcostfactor. Additionally, 
+       to be calculated fully from Up/downhillcostfactor. Additionally,
-       0.5% gives 5 m per 1km, converted to 5*60 = 300m of Elevationcost. 
+       0.5% gives 5m per 1km, converted to 5*60 = 300m of Elevationcost.
        Up to slope 2.0% the buffer value stays at 5m = elevationpenaltybuffer.
 
-   For slope 2.5%, there will remain 1.0% after cutoff subtract, 
+   For slope 2.5%, there will remain 1.0% after cutoff subtract,
        and 0.5% after the buffer reduce subtract. The remaining 0.5% accumulates in the buffer
-       by rate 5 m/km. When the buffer is full (elevationmaxbuffer), 
+       by rate 5 m/km. When the buffer is full (elevationmaxbuffer),
-       the elevation transforms to elevationcost by full rate of 1.0%, i.e. 10 m/km, 
+       the elevation transforms to elevationcost by full rate of 1.0%, i.e. 10 m/km,
        giving elevationcost 10*60=600 m/km.
 
 
-
 Technical constraints
 ---------------------
 
@@ -336,29 +340,30 @@ Technical constraints
   search area and thus to long processing times.
 
 - Forbidden ways or nodes must be treated as very high cost, because
-  there is no "forbidden" value. Technically, values >= 10000. for a
+  there is no "forbidden" value. Technically, values >= 10000 for a
-  (way-)costfactor, and >=1000000. for a nodes "initalcost" are treated
+  (way-)costfactor, and >= 1000000 for a nodes "initalcost" are treated
   as infinity, so please use these as the "forbidden" values.
 
 - Ways with costfactor >= 10000 are considered as if they did not exist at all.
 
-- Ways with costfactor = 9999 are considered as 
+- Ways with costfactor = 9999 are considered as
       if they did not exist during route calculation,
       but the navigation hint generator takes them into account.
 
 
-
 Developing and debugging scripts
 --------------------------------
 
 For developing scripts, the "brouter-web" web-application is your
-friend. You can use that either online at http://brouter/brouter-web
+friend. You can use that either online at https://brouter.de/brouter-web
 or set up a local installation.
+
 BRouter-Web has a window at the lower left corner with a "Profile"
 and a "Data" tab. Here, you can upload profile scripts and see
 the individual cost calculations per way-section in the "Data"-tab.
-Activate eventually for the profile debugging "assign processUnusedTags = true"
+
-to see on the Data tab all present OSM tags, not just those used in the tested profile.
+For profile debugging activate "assign processUnusedTags = true"
+to see all present OSM tags on the Data tab, not just those used in the tested profile.
 
 
 Lookup-Table evolution and the the "major" and "minor" versions
@@ -370,17 +375,17 @@ and a minor version number. These numbers are also encoded into
 the routing data files, taken from the lookups.dat that is used
 to pre-process the routing data files.
 
-A major version change is considered to always break compatibiliy
+A major version change is considered to always break compatibility
 between the routing datafiles and the lookup table.
 
 A minor version change keeps the routing data files and the lookup-table
 compatible in both directions, using the following rules:
 
 - if the data contains a key that is not contained in the lookup
-  tables, it is ignorned
+  tables, it is ignored
 
 - if the data contains a value that is not contained in the lookup
-  tables (but it's key is known) that value is treated as "unknown"
+  tables (but its key is known) that value is treated as "unknown"
 
 - if a profile uses a key that is not present in the data,
   it sees empty (=unset) values for that key
@@ -392,12 +397,14 @@ For a minor version change it is required that tags are only
 appended at the end of the table (or replace one of the dummy
 tags located between the way-tags and the relation pseudo-tags),
 and that values are only appended at the end of the value lists.
-This is because the routing data files adress tags and values
+This is because the routing data files address tags and values
 by their sequence numbers, so changing sequences would produce
 garbage data.
 
+
 Other resources
 ---------------
 
 See https://github.com/poutnikl/Brouter-profiles/wiki/Glossary
 as a complementary source about various profile internals.
+