Template talk:Description/Archived rationale
Rationale for this new template
Back in October 2007 Etric Celine created the very first key description template as an attempt "to get a well designed structure into the available Keys that exist to describe a map feature." Over the more-than-six years since then, this approach has grown into nearly forty such templates in over twenty languages: Lazzko created the first non-English template in July 2008 in Finnish, and German, Italian, Hungarian and other languages followed later, with Catalan being the most recent addition.
Despite some fairly advanced template magic being present in the English-language template to provide language support, the templates for non-English languages were implemented separately, and their paths have diverged somewhat ever since. While this has allowed special customisation for the different requirements of each language community, this has also meant that changes and maintenance of such a wide number of templates has been difficult. We see that with the range of different levels of implementation of the various templates, some of which include some later features from the English templates, and many of which contain links to now-non-functioning external sites. It simply is a lot of work to understand, maintain and keep up-to-date this spread of templates.
And template designing and building isn't for everyone: the proportion of people with the knowledge, time and inclination to put effort into description templates is going to be a small one, meaning that in any given language community, that group is likely to be very small indeed. As OpenStreetMap builds and grows as a true multi-language project, there needs to be an emphasis on supporting non-English communities well, particularly the newer, smaller ones.
So this reimplementation of the {{KeyDescription}} and {{ValueDescription}} templates attempts to address some of these issues, and attempts to take a serious renovation of the current setups, without affecting the visible user experience in any significant way at all. Improvement for language support, increased consistency and ease of maintenance have been the key drivers here, as well as making a few small, cosmetic tweaks in an aim to improve the overall look.
Language support
This template has been designed from the outset to support full internationalization. By separating the formatting (title, headings, etc.) from the language content, the template can be used just as well on a Japanese-language page as an English-language one. As mentioned above, this approach for this template is not new — Miloscia pioneered this approach in August 2013 — but is taken further here.
By providing excellent language support, it will be possible to migrate non-English pages away from language-specific description templates to making use of this new template, allowing changes and fixes to take place in a single place, rather than in multiple locations.
The discussion here has been moved further down the page.
Maintainability
The existing {{KeyDescription}} and {{ValueDescription}} templates have developed over some time, and are now quite difficult to understand. The new templates are built from a series of smaller templates, each with its own documentation and test cases. The new template hierarchy is as shown:
{{Template:KeyDescription}}
{{Template:ValueDescription}}
|
+---- {{Template:Description}}
|
+---- {{Template:TagPagename}} <-- link to canonical pages for key, value
|
+---- {{Template:RelationPagename}} <-- link to canonical pages for relation
|
+---- {{Template:Languages}} <-- links to the same content in other languages
|
+---- {{Template:DescriptionCategories}} <-- categorises according to group, key, value, language
| |
| +---- {{Template:DescriptionCategory}}
|
+---- {{Template:DescriptionLang}} <-- provides translations for key content
| |
| +--- {{Template:TranslateThis}} <-- encourages reader to submit a new translation
|
+---- {{Template:GroupLink}} <-- hyperlinks group name
|
+---- {{Template:ElementUsage}} <-- shows which type of elements to use this on
| |
| +---- {{Template:ElementUsage2}}
| |
| +---- {{Template:ElementUsageLang}} <-- provides translations for element usage phrases
| |
| +--- {{Template:TranslateThis}} <-- encourages reader to submit a new translation
|
+---- {{Template:StatusLang}} <-- provides translations for statuses
| |
| +--- {{Template:TranslateThis}} <-- encourages reader to submit a new translation
|
+---- {{Template:DescriptionCategory}} <-- categorises according to status
|
+---- {{Template:DescriptionLinks}} <-- links to external web pages about this key, value
|
+---- {{Template:TaginfoLinks}} <-- generate links to taginfo instances
|
+---- {{Template:TaginfoLinksPerLanguage}} <-- which taginfo instances to link to for this language
The main template is also broken down into chunks, with some explanation in the comments of what each chunk contributes.
Personalisation
If you want to personalise the look of the description boxes, the new templates give you that option. The main box is a table with class description and either keydescription or valuedescription. You can add personal CSS rules on your personal wiki CSS page to change the CSS styles which are applied. For example, adding this code:
table.description { background-color: #ccf !important; border: 3px solid black !important; }
changes the colour of description boxes to blue, and adds a wider border. The following classes are also defined:
tr.d_image
|
the table row containing the feature image |
|---|---|
tr.header
|
the table rows containing the section headers |
tr.content
|
the table rows containing the section content |
tr.d_description
|
the table rows containing the feature description title and content |
tr.d_usage
|
the table rows containing the element usage title and content |
tr.d_combination
|
the table rows containing the "useful combination" title and content |
tr.d_implies
|
the table rows containing the "implies" title and content |
tr.d_seealso
|
the table rows containing the "see also" title and content |
tr.d_status
|
the table rows containing the feature status title and content |
tr.d_taginfo
|
the table rows containing the taginfo title and content |
tr.d_links
|
the table rows containing the external links title and content |
For example, if you do not want to see taginfo details at all, the following line on your CSS page will remove them completely:
table.description tr.d_taginfo { display: none; }
Cosmetic/minor tweaks
The following minor tweaks have been made in the new templates:
- top margin reduced from .2em to 0px
- image horizontally centred within box, not left-aligned
- thin space inserted either side of the '=' in the title of the value description box
- show/hide for tag tools removed, as very few tool lines needed
- default image changed from
to 
or 
as appropriate - values in box title hyperlinked to appropriate description page, allowing easy navigation where the description box is on a different page
- improved handling where important parameters are missing
- "group" and "status" information combined: header and value on same line to reduce vertical size of box
Side-by-side comparison
Each of the following is a real-life usage of one or other of the current description templates, taken from a page on this wiki. In the case of the current templates, the template has been subst:-ed and the language links removed, simply to make the table readable. The new template is called with exactly the same parameters, except for languagelinks = no to switch off the language links, and lang = ?? to indicate which language to use.
| Parameters | Current template | New template | |
|---|---|---|---|
{{ValueDescription
| key = highway
| value = trunk
| image = Image:Dscf0444 600.jpg
| description = Important roads that aren't motorways.
| onNode = no
| onWay = yes
| onArea = no
| lang = en
| combination =
* {{Tag|name}}
* {{Tag|ref}}
* {{tag|motorroad}}
* {{Tag|oneway|yes}}
* {{Tag|lanes}}
* {{Tag|destination}}
| implies =
* {{tag|surface|paved}}
}}
|
|
| |
{{Template:De:ValueDescription
| description=Ein Geschäft für Autoteile, Autozubehör, Motoröl usw.
}}
|
|
| |
{{KeyDescription
| image = File:Disused-pub.jpg
| key = disused
| value = *
| description = Namespace for features that have fallen into disuse, \
but which are still useful for navigation and visible in the landscape.
| group = Lifecycle
| onNode = yes
| onWay = yes
| onArea = yes
| status = In use
| seeAlso = {{tag|abandoned}}
| lang = en
}}
|
|
| |
{{Template:RU:KeyDescription
|key = cuisine
|image = Image:Burger 1 bg 080206.jpg
|description = Для описания типа еды предлагаемой в ресторане или кафе
|group = cuisine
|onNode = yes
|onWay = no
|onArea = yes
|onRelation = no
|lang = en
|combination=
* {{Template:RU:Tag|amenity|restaurant}}
* {{Template:Tag|takeaway||yes/no}}
* {{Template:Tag|diet}}
}}
|
|
|
.jpg)
Implementation plan
The following implementation seems sensible, with enough time for each stage/between stages to check that nothing is going too wrong.
- Stage 1: publish this outline here, encourage discussion, identify and address any bugs, problems, concerns or questions; use this template in a small number of real pages to check for compatibility across more real-world usages, languages, etc.
- The following pages are being used to test these templates:
- Stage 2: once reasonable consensus has been achieved, select a medium-sized language group and move usage of existing language-specific template to this one, checking for compatibility, readability, etc.
- Updated seven pages which included {{Fi:ValueDescription}} but did not have
lang =parameter specified: setlang = fi - Replaced Template:Fi:ValueDescription with redirect to User:Moresby/ValueDescription
- These pages now using new template:
- Updated seven pages which included {{Fi:ValueDescription}} but did not have
- Fi:Tag:amenity=atm
- Fi:Tag:amenity=baby_hatch
- Fi:Tag:amenity=bank
- Fi:Tag:amenity=bicycle_parking
- Fi:Tag:amenity=bicycle_rental
- Fi:Tag:amenity=bureau_de_change
- Fi:Tag:amenity=car_rental
- Fi:Tag:amenity=car_sharing
- Fi:Tag:amenity=cinema
- Fi:Tag:amenity=courthouse
- Fi:Tag:amenity=crematorium
- Fi:Tag:amenity=embassy
- Fi:Tag:amenity=ferry_terminal
- Fi:Tag:amenity=fire_station
- Fi:Tag:amenity=fountain
- Fi:Tag:amenity=fuel
- Fi:Tag:amenity=library
- Fi:Tag:amenity=nightclub
- Fi:Tag:amenity=police
- Fi:Tag:amenity=prison
- Fi:Tag:amenity=recycling
- Fi:Tag:amenity=telephone
- Fi:Tag:amenity=theatre
- Fi:Tag:amenity=townhall
- Fi:Tag:amenity=veterinary
- Fi:Tag:building=garage
- Fi:Tag:building=garages
- Fi:Tag:highway=crossing
- Fi:Tag:highway=footway
- Fi:Tag:highway=secondary
- Fi:Tag:highway=speed_camera
- Fi:Tag:highway=steps
- Fi:Tag:highway=tertiary
- Fi:Tag:highway=unclassified
- Fi:Tag:leisure=dog_park
- Fi:Tag:leisure=slipway
- Fi:Tag:man_made=wastewater_plant
- Fi:Tag:man_made=watermill
- Fi:Tag:natural=tree
- Fi:Tag:natural=wetland
- Fi:Tag:power=tower
- Fi:Tag:railway=crossing
- Fi:Tag:railway=level_crossing
- Fi:Tag:service=parking_aisle
- Fi:Tag:shop=bakery
- Fi:Tag:shop=bicycle
- Fi:Tag:shop=butcher
- Fi:Tag:shop=car
- Fi:Tag:shop=dry_cleaning
- Fi:Tag:sport=shooting
- Fi:Tag:tourism=hotel
- Fi:Tag:tourism=zoo
- Fi:Tag:waterway=river
- Fi:Tag:waterway=stream
- Replaced Template:NL:KeyDescription with redirect to User:Moresby/KeyDescription
- These pages now using new template:
- NL:Key:cycleway
- NL:Key:building
- NL:Key:amenity
- NL:Key:demolished
- NL:Key:office
- NL:Key:addr
- NL:Key:man_made
- NL:Key:shop
- NL:Key:tourism
- NL:Key:craft
- NL:Key:emergency
- NL:Key:public_transport
- NL:Key:name
- NL:Key:type
- NL:Key:route_master
- NL:Key:colour
- NL:Key:landuse
- NL:Key:military
- NL:Key:natural
- NL:Key:leisure
- NL:Key:fenced
- NL:Key:fence_type
- NL:Key:barrier
- NL:Key:backrest
- NL:Key:bench
- NL:Key:waste
- Stage 3: assuming no showstoppers, replace one or other of {{KeyDescription}} or {{ValueDescription}} with the new template
- {{ValueDescription}} replaced with a redirect to User:Moresby/ValueDescription at around 2014-04-14 21:30 GMT.
- Stage 4: replace the other with the new template
- {{KeyDescription}} replaced with a redirect to User:Moresby/KeyDescription at around 2014-04-17 22:30 GMT.
- reverted by User:Pigsonthewing at around 2014-04-17 23:00 GMT — discussion.
- Extra
url_patternadded, and redirect reinstated at around 2014-04-18 15:35 GMT.
- Stage 5: redirect language templates to User:Moresby/KeyDescription or User:Moresby/ValueDescription as appropriate, identifying any remaining language-specific features and incorporating as appropriate
- Stage 6: update individual description pages to point to {{KeyDescription}} or {{ValueDescription}}, retaining page-specific parameters
| Page name | Migrated |
|---|---|
| JA:Tag:amenity=pub | 2014-04-21 18:04:17 GMT |
| JA:Tag:amenity=bar | 2014-04-21 18:04:23 GMT |
| Page name | Migrated |
|---|---|
| El:Key:building:levels | 2014-04-22 17:44:45 GMT |
| El:Key:height | 2014-04-22 17:44:52 GMT |
| Page name | Migrated |
|---|---|
| Sv:Key:name | 2014-04-22 18:04:02 GMT |
| Page name | Migrated |
|---|---|
| FR:Key:overtaking | 2014-04-23 07:35:55 GMT |
| Page name | Migrated |
|---|---|
| Lt:Key:cycleway | 2014-04-23 18:15:13 GMT |
| Page name | Migrated |
|---|---|
| Da:Key:access | 2014-04-23 20:37:44 GMT |
| Page name | Migrated |
|---|---|
| Ar:Tag:shop=bakery | 2014-04-23 20:40:05 GMT |
| Ar:Tag:amenity=school | 2014-04-23 20:40:11 GMT |
| Page name | Migrated |
|---|---|
| Ro:Key:amenity | 2014-04-23 21:21:04 GMT |
| Page name | Migrated |
|---|---|
| Ca:Key:name | 2014-04-23 21:48:43 GMT |
| Page name | Migrated |
|---|---|
| Ar:Key:name | 2014-04-23 21:51:24 GMT |
- Stage 7: replace content of {{KeyDescription}} and {{ValueDescription}} with code from User:Moresby/KeyDescription and User:Moresby/ValueDescription
- Stage 8: collect and find appropriate places for documentation and discussion