Subversion Repositories mkgmap

[[FILES]]
= The structure of a style =

A style consists of a number of files in a single directory. The best way
is to start out with an existing style that is close to what you want and
then work from there.

A style can be packed into a single file using the standard zip utilities
that are available on every operating system, or it can be written as one
large text file using the single file style format. These alternatives
are explained in <<style-packaging,making a style package>>.

== Files ==
These files are read in the order that they are listed here. In general, files that are read first take priority over files read later.
The only one of these files that is actually required is the +version+
file, as that is used to recognise the style.
At least one of the +points+, +lines+ or +polygons+ files must be present
or else the resulting maps will be empty.

=== Top level folder ===
Choose a short name for your style, it should be one word or a couple of words joined by an underscore or hyphen.  This is how people will refer to the style when it is finished.
Create a directory or folder with that name.  Then you must create one or
more files in this directory as detailed below.  Only the +version+ file is required.

== The version file
This file _must_ exist as it is used to recognise a valid style.
It contains the version number of the style language itself, (not the
version number of your style, which you can specify in the +info+ file
if you so wish).
The current version number of the style language is 1.
Make sure that there is a new line after the number, place an empty line afterwards to be sure.

== The info file
This file contains information about your style.
It is all optional information, and there is only really any point
adding this information if you are going to distribute your style, or
you have more than one style that you maintain.

The file consists of key=value pairs in the same syntax as the
command line option file. To summarise you can use either an equal sign
'=' or a colon ':' to separate the key from the value. You can also
surround the value with curly braces '{ }' and this allows you to
write the value over several lines.

[horizontal]
version:: The version number of your style.

summary:: A short description of your style in one line.

description:: A longer description of your style.

base-style:: Do not use anymore. This was used to base a style on
another one. However, it is bug prone and behaves in a way that is not
intuitive without a good understanding of how things work.
The preferred way to do this is to use the include mechanism.
This command will be removed altogether at some point in the future.

.An example info file
====
Here is an example based on the +info+ file from the default style.
You can see it uses both equal and colon as separators, normally you
would just pick one and use it consistently, but it doesn't make any
difference which one you use.
The description is written over several lines surrounded in curly
brackets.
Lines beginning with a hash symbol '#' are comments and are ignored.
----
#
# This file contains information about the style.
#

summary: The default style

version=1.0

description {
The default style.  This is a heavyweight style that is
designed for use when mapping and especially in lightly covered
areas.
}
----
====


== The options file
This file contains a number of options that should be set for this style
as if they were set on the command line.
Only command line options that affect the style will have any effect.
The current list is +levels+, +overview-levels+, and +extra-used-tags+.

It is advisable to set up the levels that you want, as the default is not
suitable for all kinds of maps and may change in the future.  Ideally,
you should set the same levels as are used in your style files.  For
example, if your style files use levels 12,16,20,22,23,24 then it's a
good idea to make sure your options style file declares these levels
explicitly.

.An example options file
====
 levels = 0:24, 1:22, 2:20, 3:18 
 overview-levels = 4:17, 5:16, 6:15, 7:14, 8:12  
 extra-used-tags=
====

=== Non command line options
Most of the options are the same as the command line option of the same
name and so you should see its description in the option help.
There are however some options that can only be set in this file
(just the currently).

extra-used-tags:: A list of tags used by the style. You do not normally
need to set this, as mkgmap can work out which tags are used by a style
automatically in most cases. It exists only to work around cases where
this doesn't work properly.

== The points file
This files contains a set of rules for converting
OSM nodes to Garmin POIs (restaurants, bars, ATMs etc).
It can also contain rules for some kind of OSM nodes that may
affect routing behavior, for example barriers, traffic_calming, traffic_signals, etc.

If this file is not present or empty then there will be no POI's in the
final map.

The syntax of the file is described in the <<RULES,style rules section>>.
Like all other files, a hash symbol '#' introduces a comment.

== The lines file
This file contains a set of rules for converting OSM ways to Garmin lines (roads, rivers, barriers, etc).
The syntax of the file is described in the <<RULES,style rules section>>.

== The polygons file
This file contains a set of rules for converting polygons to Garmin
areas (fields, buildings, residential areas, etc).
The syntax of the file is described in the <<RULES,style rules section>>.

== The relations file
This file contains a set of rules to convert OSM relations.
Unlike the +points+, +lines+ and +polygons+ files this file does not lead
directly to a Garmin object.
Instead it is used to modify the ways or nodes that are contained in the
relation.

So for example, if the relation represents a route, then you might add one
or more tags to all the ways that make up the route so that they can be
processed in the +lines+ file specially.

The syntax of the file is also described in the <<RULES,style rules section>>,
but the rules can only have an action part, they must not have a type
description part.

////
== The overlays file
The idea of this file
Used where you want a single way to be converted to two ways in the output map (for example a road might be rendered as normal but an additional line is created if the road is oneway - this then allows you to use a TYP file to add oneway arrows to the road).  An example of use might be:

In the lines file:
-----
highway=trunk & oneway=yes [0x123 road_class=3 road_speed=5 resolution 16]
-----

In the overlays file:
----
0x123:  0x02, 0x23
----

Then set the TYP file contain arrows for code 0x23.

Note that only the first way in the overlays file is routable.
////