trunk/doc/CONFIGURATION.txt

                           Routino : Configuration
                           =======================


   New in version 1.4 of Routino is the use of configuration files to
   allow more information to be provided to the programs at run-time. The
   configuration files that are used are:
     * Tagging transformation rules for the planetsplitter program.
     * Routing profiles for the router program.
     * Output translations for the router program.

   In keeping with the nature of the input and output files the
   configuration files are also XML files. Each of the files uses a custom
   defined XML schema and an XSD file is provided for each of them.


Tag Transformation Rules
------------------------

   The default name of the tagging transformation rules XML configuration
   file is tagging.xml in the same directory as the generated database
   files. Other filenames can be specified on the command line using the
   --tagging option. When processing the input it is possible to have a
   different set of tagging rules for each file; for example different
   rules for different countries.

   The tagging rules allow modifying the highway tags in the source file
   so that the routing can be performed on a simpler set of tags. This
   removes the special case tagging rules from the source code into the
   configuration file where they can be easily modified. Part of the
   provided tagging.xml file showing the rules for motorway_link and
   motorway highway types.

<?xml version="1.0" encoding="utf-8"?>
<routino-tagging>

  <way>

    <if k="highway" v="motorway_link">
      <set v="motorway"/>
    </if>

    <if k="highway" v="motorway">
      <output k="highway"/>

      <output k="motorcycle" v="yes"/>
      <output k="motorcar"   v="yes"/>
      <output k="goods"      v="yes"/>
      <output k="hgv"        v="yes"/>
      <output k="psv"        v="yes"/>

      <output k="paved"      v="yes"/>
      <output k="multilane"  v="yes"/>
      <output k="oneway"     v="yes"/>

      <unset k="highway"/>
    </if>
...
  <way>

</routino-tagging>

   The rules all have the same format; an if or ifnot element at the top
   level for matching the input and some other elements inside to be used
   if there was a match.

   Within the if and ifnot rules any of the rules can be used. These are
   if, ifnot, set, unset, output or logerror elements.

   The rules for matching the if or ifnot elements are the following:
     * An if rule that has both k and v specified is only matched if a tag
       exists in the input that matches both.
     * An if rule that has only the k attribute is matched if a tag with
       that key exists.
     * An if rule that has only the v attribute is matched for each tag
       with that value (i.e. the contents may be used more than once).
     * An if rule that has neither attribute specified always matches.
     * An ifnot rule that has both k and v specified is only matched if no
       tag exists in the input that matches both.
     * An ifnot rule that has only the k attribute is matched only if no
       tag with that key exists.
     * An ifnot rule that has only the v attribute is only matched if no
       tag with that value exists.
     * An ifnot rule that has neither attribute specified never matches.

   For set, unset, output or logerror elements inside of an if rule an
   unspecified value for the k or v attribute is replaced by the values
   from the tag that matched the outer if rule. This makes it simple to
   delete tags that match a particular rule without having to specify the
   parameters more than once. For elements inside of an ifnot element an
   unspecified value for the k or v attribute is replaced by the values
   from the outer ifnot rule. This means that either the outer ifnot
   element or the inner element must specify both k and v attributes
   between them. For nested if or ifnot elements the outer k and v
   attributes are not inherited by the inner elements.

   The set and unset elements either create or delete a tag from the input
   data that was read from the file. If the set element is used and the
   tag already exists then it is modified. The output element adds a tag
   to the set that will be used by Routino to determine the data
   properties.

   The logerror element will cause an error message to be added to the
   error log file that reports that the key and attribute combination are
   not recognised. If the k attribute is specified but not the v attribute
   then the tag value that matches the specified key is looked up and
   used. An additional message attribute can be specified to be printed at
   the end of the logged error.

   The default logged error message is:

   Node XXX has an unrecognised tag 'key' = 'value' (in tagging rules); ignoring it.

   The specified message attribute will replace the final part of the
   logged error.


Routing Profiles
----------------

   The default name of the routing profiles XML configuration file is
   profiles.xml in the same directory as the database files. Other
   filenames can be specified on the command line using the --tagging
   option.

   The purpose of this configuration file is to allow easy modification of
   the routing parameters so that they do not all need to be specified on
   the command line. In versions of Routino before version 1.4 the default
   routing parameters (preferred highways, preferred speeds etc) were
   contained in the source code, now they are in a configuration file.
   When calculating a route the --profile option selects the named profile
   from the configuration file.

   Part of the provided profiles.xml file showing the parameters for
   transport on foot is shown below:

<?xml version="1.0" encoding="UTF-8" ?>
<routino-profiles>

  <profile name="foot" transport="foot">
    <speeds>
...
      <speed highway="cycleway"      kph="4" />
      <speed highway="path"          kph="4" />
      <speed highway="steps"         kph="4" />
    </speeds>
    <preferences>
...
      <preference highway="cycleway"      percent="95" />
      <preference highway="path"          percent="100" />
      <preference highway="steps"         percent="80" />
    </preferences>
    <properties>
      <property type="paved"        percent="50" />
      <property type="multilane"    percent="25" />
      <property type="bridge"       percent="50" />
      <property type="tunnel"       percent="50" />
...
    </properties>
    <restrictions>
      <oneway obey="0" />
      <weight limit="0.0" />
      <height limit="0.0" />
      <width  limit="0.0" />
      <length limit="0.0" />
    </restrictions>
  </profile>
  <profile name="horse" transport="horse">
...
  </profile>
...
</routino-profiles>


Output Translations
-------------------

   The default name of the output translations XML configuration file is
   translations.xml in the same directory as the database files. Other
   filenames can be specified on the command line using the --translations
   option.

   The generated HTML and GPX output files (described in the next section)
   are created using the fragments of text that are defined in this file.
   Additional languages can be added to the file and are selected using
   the --language option to the router. If no language is specified the
   first one in the file is used.

   Part of the provided translations.xml file showing some of the English
   language (en) translations is shown below:

<?xml version="1.0" encoding="utf-8"?>
<routino-translations>

  <language lang="en">
...
    <turn direction="-4" string="Very sharp left" />
    <turn direction="-3" string="Sharp left" />
    <turn direction="-2" string="Left" />
...
    <heading direction="-4" string="South" />
    <heading direction="-3" string="South-West" />
    <heading direction="-2" string="West" />
...
    <route type="shortest" string="Shortest" />
    <route type="quickest" string="Quickest" />
    <output-html>
...
    </output-html>
    <output-gpx>
...
    </output-gpx>
  </language>
</routino-translations>


--------

Copyright 2010-2013 Andrew M. Bishop.
1	Routino : Configuration
2	=======================
3
4
5	New in version 1.4 of Routino is the use of configuration files to
6	allow more information to be provided to the programs at run-time. The
7	configuration files that are used are:
8	* Tagging transformation rules for the planetsplitter program.
9	* Routing profiles for the router program.
10	* Output translations for the router program.
11
12	In keeping with the nature of the input and output files the
13	configuration files are also XML files. Each of the files uses a custom
14	defined XML schema and an XSD file is provided for each of them.
15
16
17	Tag Transformation Rules
18	------------------------
19
20	The default name of the tagging transformation rules XML configuration
21	file is tagging.xml in the same directory as the generated database
22	files. Other filenames can be specified on the command line using the
23	--tagging option. When processing the input it is possible to have a
24	different set of tagging rules for each file; for example different
25	rules for different countries.
26
27	The tagging rules allow modifying the highway tags in the source file
28	so that the routing can be performed on a simpler set of tags. This
29	removes the special case tagging rules from the source code into the
30	configuration file where they can be easily modified. Part of the
31	provided tagging.xml file showing the rules for motorway_link and
32	motorway highway types.
33
34	<?xml version="1.0" encoding="utf-8"?>
35	<routino-tagging>
36
37	<way>
38
39	<if k="highway" v="motorway_link">
40	<set v="motorway"/>
41	</if>
42
43	<if k="highway" v="motorway">
44	<output k="highway"/>
45
46	<output k="motorcycle" v="yes"/>
47	<output k="motorcar" v="yes"/>
48	<output k="goods" v="yes"/>
49	<output k="hgv" v="yes"/>
50	<output k="psv" v="yes"/>
51
52	<output k="paved" v="yes"/>
53	<output k="multilane" v="yes"/>
54	<output k="oneway" v="yes"/>
55
56	<unset k="highway"/>
57	</if>
58	...
59	<way>
60
61	</routino-tagging>
62
63	The rules all have the same format; an if or ifnot element at the top
64	level for matching the input and some other elements inside to be used
65	if there was a match.
66
67	Within the if and ifnot rules any of the rules can be used. These are
68	if, ifnot, set, unset, output or logerror elements.
69
70	The rules for matching the if or ifnot elements are the following:
71	* An if rule that has both k and v specified is only matched if a tag
72	exists in the input that matches both.
73	* An if rule that has only the k attribute is matched if a tag with
74	that key exists.
75	* An if rule that has only the v attribute is matched for each tag
76	with that value (i.e. the contents may be used more than once).
77	* An if rule that has neither attribute specified always matches.
78	* An ifnot rule that has both k and v specified is only matched if no
79	tag exists in the input that matches both.
80	* An ifnot rule that has only the k attribute is matched only if no
81	tag with that key exists.
82	* An ifnot rule that has only the v attribute is only matched if no
83	tag with that value exists.
84	* An ifnot rule that has neither attribute specified never matches.
85
86	For set, unset, output or logerror elements inside of an if rule an
87	unspecified value for the k or v attribute is replaced by the values
88	from the tag that matched the outer if rule. This makes it simple to
89	delete tags that match a particular rule without having to specify the
90	parameters more than once. For elements inside of an ifnot element an
91	unspecified value for the k or v attribute is replaced by the values
92	from the outer ifnot rule. This means that either the outer ifnot
93	element or the inner element must specify both k and v attributes
94	between them. For nested if or ifnot elements the outer k and v
95	attributes are not inherited by the inner elements.
96
97	The set and unset elements either create or delete a tag from the input
98	data that was read from the file. If the set element is used and the
99	tag already exists then it is modified. The output element adds a tag
100	to the set that will be used by Routino to determine the data
101	properties.
102
103	The logerror element will cause an error message to be added to the
104	error log file that reports that the key and attribute combination are
105	not recognised. If the k attribute is specified but not the v attribute
106	then the tag value that matches the specified key is looked up and
107	used. An additional message attribute can be specified to be printed at
108	the end of the logged error.
109
110	The default logged error message is:
111
112	Node XXX has an unrecognised tag 'key' = 'value' (in tagging rules); ignoring it.
113
114	The specified message attribute will replace the final part of the
115	logged error.
116
117
118	Routing Profiles
119	----------------
120
121	The default name of the routing profiles XML configuration file is
122	profiles.xml in the same directory as the database files. Other
123	filenames can be specified on the command line using the --tagging
124	option.
125
126	The purpose of this configuration file is to allow easy modification of
127	the routing parameters so that they do not all need to be specified on
128	the command line. In versions of Routino before version 1.4 the default
129	routing parameters (preferred highways, preferred speeds etc) were
130	contained in the source code, now they are in a configuration file.
131	When calculating a route the --profile option selects the named profile
132	from the configuration file.
133
134	Part of the provided profiles.xml file showing the parameters for
135	transport on foot is shown below:
136
137	<?xml version="1.0" encoding="UTF-8" ?>
138	<routino-profiles>
139
140	<profile name="foot" transport="foot">
141	<speeds>
142	...
143	<speed highway="cycleway" kph="4" />
144	<speed highway="path" kph="4" />
145	<speed highway="steps" kph="4" />
146	</speeds>
147	<preferences>
148	...
149	<preference highway="cycleway" percent="95" />
150	<preference highway="path" percent="100" />
151	<preference highway="steps" percent="80" />
152	</preferences>
153	<properties>
154	<property type="paved" percent="50" />
155	<property type="multilane" percent="25" />
156	<property type="bridge" percent="50" />
157	<property type="tunnel" percent="50" />
158	...
159	</properties>
160	<restrictions>
161	<oneway obey="0" />
162	<weight limit="0.0" />
163	<height limit="0.0" />
164	<width limit="0.0" />
165	<length limit="0.0" />
166	</restrictions>
167	</profile>
168	<profile name="horse" transport="horse">
169	...
170	</profile>
171	...
172	</routino-profiles>
173
174
175	Output Translations
176	-------------------
177
178	The default name of the output translations XML configuration file is
179	translations.xml in the same directory as the database files. Other
180	filenames can be specified on the command line using the --translations
181	option.
182
183	The generated HTML and GPX output files (described in the next section)
184	are created using the fragments of text that are defined in this file.
185	Additional languages can be added to the file and are selected using
186	the --language option to the router. If no language is specified the
187	first one in the file is used.
188
189	Part of the provided translations.xml file showing some of the English
190	language (en) translations is shown below:
191
192	<?xml version="1.0" encoding="utf-8"?>
193	<routino-translations>
194
195	<language lang="en">
196	...
197	<turn direction="-4" string="Very sharp left" />
198	<turn direction="-3" string="Sharp left" />
199	<turn direction="-2" string="Left" />
200	...
201	<heading direction="-4" string="South" />
202	<heading direction="-3" string="South-West" />
203	<heading direction="-2" string="West" />
204	...
205	<route type="shortest" string="Shortest" />
206	<route type="quickest" string="Quickest" />
207	<output-html>
208	...
209	</output-html>
210	<output-gpx>
211	...
212	</output-gpx>
213	</language>
214	</routino-translations>
215
216
217	--------
218
219	Copyright 2010-2013 Andrew M. Bishop.