Clarify guidelines for adding shield support for new countries

[claysmalley]

There's been a wave of contributions lately, adding route shield support for non-US countries. We should make it more obvious what the prerequisites are for supporting route=road tagging schemes in OSM-Americana.

Some guidelines off the top of my head:

• Values of network=* must begin with the country's ISO 3166-1 alpha-2 code, followed by a colon :. The country's alpha-2 code alone may also be used as a value of network=*.
  • Or, if this is a route network assigned by an international organization (to which country codes would not apply), the value of network=* must be globally unique, avoiding conflict with existing values of network=*. It must be at least 3 characters long to avoid collision with country codes.
• Each value of network=* must correspond to only one shield design. We must be able to use network=* to determine which route shield design is ~used on the ground~ intended to be displayed.
• The tagging scheme of network=* should be free of unnecessary complexities. It should be easy for other software projects to work with.
  • For example, Interstate Highways in the US are tagged network=US:I without specifying which state they are in. In real life, many Interstate Highway shields have the name of the state on them, and some routes have numbers duplicated in other states (with no plans to ever connect routes with the same numbers). One might assume this implies that an Interstate Highway in California should be tagged network=US:I:CA, but fundamentally, the route numbers themselves (even the duplicate ones) are assigned by a federal agency and not the states. These are clearly a national network, and the presence of the state name is functionally just a decoration. So all US Interstates belong to a single network, and are not split up by state.
• The value of ref=* must not contain extra text (prefixes or suffixes) that needs to be removed before displaying. Values of ref=* should only need preprocessing in limited circumstances.
  • ref=* values on relations need not match ref=* values on ways. For example, the prefix I is present on US Interstate Highways in the ref=* values of ways, but not in relations. A simple map renderer will apply a generic shield to the ref=* value of the way, so it is necessary to use a prefix to identify that it belongs to the Interstate network. But a more complex map renderer, such as OSM-Americana, will use the values of network=* and ref=* in route=road relations to determine which shield to render. The prefix is not present on shields, and network=US:I is enough to determine that a US Interstate shield should be drawn, so ref=* has no prefix in relations.
• The tagging scheme must enjoy local consensus. The rest of the mapping community in the country affected must agree with this tagging scheme.
  • If this is a small country where there may only be one or two active mappers, the route tagging scheme is likely to be uncomplicated. "Consensus" may not be necessary in this case, but as long as the mapping community is notified, it's probably okay.
• Each value of network=* must be documented on the OSM Wiki. When a mapper finds a value of network=* in an OSM tool like iD, JOSM or Taginfo, they should be able to click on the Wiki link next to it to find details on what the value of network=* represents, and where to use it.
  • Example: Tag:network=US:VA:Secondary
• Some route relations for each value of network=* must be mapped on OSM in order for us to test them.

[1ec5]

The value of ref= must not contain extra text (prefixes or suffixes) that needs to be removed before displaying. Likewise, it must not require a hardcoded prefix or suffix to be added. We must be able to show ref= directly as the route number on the shield, without preprocessing.

This has come up as a problem enough times that I wonder if we should formally propose it as a standard on the wiki. The “without preprocessing” part is critical: there may be some resistance to the idea of tailoring ref tags to Americana’s needs, but it’s possible to express the same requirement in more basic terms. In principle, ref should only include a prefix that’s an integral part of the route number, not just for the purpose of disambiguation in certain OSM contexts. The rationale is to avoid the same proliferation of haphazard, often proprietary ref processing rules for route relations as has already occurred for ways.

[claysmalley]

Should we resolve #141 as won't fix?

[1ec5]

Should we resolve #141 as won't fix?

I don’t find that issue’s original rationale very compelling, given the rabbit hole we’d find ourselves in, but we will run into some need for concatenation and possibly numeral conversion: https://github.com/ZeLonewolf/openstreetmap-americana/issues/141#issuecomment-1046409219.

[zekefarwell]

This has come up as a problem enough times that I wonder if we should formally propose it as a standard on the wiki. The “without preprocessing” part is critical

Somehow I thought the wiki already stated that ref on a route relation should be the value most commonly used on signage (no extra prefixes or suffixes). I just looked around and couldn't find such a statement though. We certainly should add this somewhere on the wiki, though I'm not sure where would be most appropriate.

[1ec5]

I added a brief mention in the examples section of the ref documentation back in 2014, but it’s easy to overlook.