Code improvement: explain roads styling.

[StyXman]

At the top of roads.mss, right after the variable definitions, I wrote this:

The structure of the styling goes like this:

There are two types of lines: encased and simple.

Encased lines are all major roads (motorway to tertiary) and all minor roads (residential to pedestrian)
simple lines are all paths (track, steps, bridleway, footway, path, cycleway) and trains (rail,
monorail, tram, subway, light_rail, funicular, narrow_gauge)

encased lines have a coloured fill and can be in thin mode (< ZL12, width < 3) with a halo,
or a thick mode (>= ZL12, width > 3) with a casing.

simple lines are just a line with a casing and a background in case of tunnels or bridges.

There are 5 layers (in order of definition/drawing, lower to higher):

* #tunnels
* #roads-casing
* #roads-fill
* #roads-low-zoom
* #bridges

tunnels, roads-casing and bridges are grouped in the first style, but then differentiated again.
  inside there are two attachments, ::casing and ::bridges_and_tunnels_background
    for simple lines, tunnels and bridges have an outer border and a background
  this style provides the borders of the line, only for >= ZL12

tunnels, roads-fill, roads-low-zoom and bridges are grouped in the second style, but then differentiated again.
  inside there are two attachments, ::halo and ::fill
    ::halo provides a highlight background for simple lines for mayor roads for < ZL12
    ::fill is the final fill

so in all you get:

--- semi transparent
=== solid
= = dotted
··· background
*** fill colour
+++ lighter fill
### black
* * dotted fill

< ZL12
                road       tunnel     bridge
* major roads
                -------    -------    -------  ::halo
                *******    *******    *******  ::fill
                -------    -------    -------  ::halo

>= ZL12
* motorway, trunk
                =======    = = = =    #######  ::casing
                *******    +++++++    *******  :: fill
                =======    = = = =    #######  ::casing

* paved primary, secondary, tertiary,
                =======    = = = =    #######  ::casing
                *******    +++++++    *******  :: fill
                =======    = = = =    #######  ::casing

* unpaved primary, secondary, tertiary, residential, unclassified, road, service, living_street
                == == =    = = = =    #######  ::casing
                *******    +++++++    *******  :: fill
                == == =    = = = =    #######  ::casing

* pedestrian
                           = = = =    #######  ::casing
                *******    +++++++    *******  :: fill
                           = = = =    #######  ::casing

* steps, bridleway, footway, path, cycleway, track
                           = = = =    #######  ::casing
                           ·······    ·······  ::bridges_and_tunnels_background
                *******    +++++++    *******  :: fill
                           ·······    ·······  ::bridges_and_tunnels_background
                           = = = =    #######  ::casing

* trains
                                      #######  ::casing
                                      ·······  ::bridges_and_tunnels_background
                *******    + + + +    *******  :: fill
                                      ·······  ::bridges_and_tunnels_background
                                      #######  ::casing


Widths include casing and bridges, except for tunnels and bridges on simple lines.

There are a few details missing and there might be some local stuff. If you're interested I can make a PR; otherwise just close this one and at least it will be doc'ed here.

[imagico]

This looks right at a quick read and i would not mind adding this to the code. The most useful documentation otherwise about the road layers is probably what i wrote here.

That being said - there is a larger background here i would like to explain a bit:

As many know OSM-Carto has the most sophisticated system of road rendering of all operational OSM based maps. Its complexity allows us - more than most other map styles - to highlight and provide feedback on the semantic and structural details recorded in OSM data about roads. But it also creates a substantial barrier to contributors to the map style and makes any changes to road rendering a challenge.

In light of this improving documentation of our road rendering system would be of immense value. Not only in the short term for OSM-Carto development but also in the long term for the future of OpenStreetMap as a whole and for map design in general. There are only a hand full of people at the moment who have an in-depth understanding how road rendering in OSM-Carto works - and for most of them this is already historic knowledge (meaning: they are not active in CartoCSS/Mapnik map style development any more).

Unfortunately, those who would have the economic capacity to do so (companies using OSM data, academic institutions, to a lesser extent the OSMF) have shown no interest in investing in the historic memory of OpenStreetMap. And while we, in OSM-Carto, recognize the immense value of this knowledge for the future of OpenStreetMap and OSM based map design we of course lack the economic means to ensure this knowledge is preserved for future generations.

So if anyone following this issue tracker has the means to support an endeavor to preserve the 1.5 decades of historic knowledge and map design experience around the development of OSM-Carto and to document how the most sophisticated operational OSM based map style works or has the means to lobby those who have these means to invest here then please feel highly encouraged to become active here.