Template talk:Description/Archived rationale

From OpenStreetMap Wiki
Jump to navigation Jump to search

Rationale for this new template

Key and value description templates
Languageik Key description template Value description template
ar {{Ar:KeyDescription}} {{Ar:ValueDescription}}
ca {{Ca:KeyDescription}} {{Ca:ValueDescription}}
cs {{Cs:KeyDescription}} {{Cs:ValueDescription}}
da {{Da:KeyDescription}} {{Da:ValueDescription}}
de {{Template:DE:KeyDescription}} {{Template:DE:ValueDescription}}
en {{KeyDescription}} {{ValueDescription}}
es {{Template:ES:KeyDescription}} {{Template:ES:ValueDescription}}
fi {{Fi:KeyDescription}} {{Fi:ValueDescription}}
fr {{Template:FR:KeyDescription}} {{Template:FR:ValueDescription}}
hu {{Hu:KeyDescription}} {{Hu:ValueDescription}}
it {{Template:IT:KeyDescription}} {{Template:IT:ValueDescription}}
ja {{Template:JA:KeyDescription}} {{Template:JA:ValueDescription}}
lt {{Lt:KeyDescription}} {{Lt:ValueDescription}}
nl {{Template:NL:KeyDescription}} {{Template:NL:ValueDescription}}
pl {{Pl:KeyDescription}} {{Pl:ValueDescription}}
pt {{Pt:KeyDescription}} {{Pt:ValueDescription}}
ro {{Ro:KeyDescription}} {{Ro:ValueDescription}}
ru {{Template:RU:KeyDescription}} {{Template:RU:ValueDescription}}
sv {{Sv:KeyDescription}} {{Sv:ValueDescription}}
uk {{Uk:KeyDescription}} {{Uk:ValueDescription}}
zh-hans {{Zh-hans:KeyDescription}} {{Zh-hans:ValueDescription}}

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 None yet.jpg to Osm element key.svg or Osm element tag.svg 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}}
}}


+/-Public-images-osm logo.svg highway=trunk

One example for highway=trunk

Description

Important roads that aren't motorways.

Used on these elements

should not be used on nodes may be used on ways should not be used on areas use on relations unspecified

Useful combination
Implies
Status:

Undefined Status: Undefined


{{Template:De:ValueDescription
| description=Ein Geschäft für Autoteile, Autozubehör, Motoröl usw.
}}


+/-

[[De:Key:{{{key}}}|{{{key}}}]]={{{value}}}


Beschreibung

Ein Geschäft für Autoteile, Autozubehör, Motoröl usw.

Status

Undefined Status: Undefined Hilfe



{{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
}}


+/- disused

One example for disused

Description

Namespace for features that have fallen into disuse, but which are still useful for navigation and visible in the landscape.

Group

Lifecycle

Used on these elements

may be used on nodes may be used on ways may be used on areas use on relations unspecified

See also

abandoned=*

Status:

In use Status: In Use



{{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}}
}}


+/- cuisine

Один из примеров cuisine

Описание

Для описания типа еды предлагаемой в ресторане или кафе

Относится к группе

cuisine

Назначается на эти элементы: Справка
точки можно отмечать этим тегомлинии не принято отмечать этим тегомполигоны можно отмечать этим тегомотношения не принято отмечать этим тегом
Полезные сочетания
Статистика применения
Статус

Не указан



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.
Key and value description templates
Language Key description template Migrated Value description template Migrated
ar {{Ar:KeyDescription}} 2014-04-19 14:32 GMT {{Ar:ValueDescription}} 2014-04-19 14:03 GMT
ca {{Ca:KeyDescription}} 2014-04-19 14:38 GMT {{Ca:ValueDescription}} -
cs {{Cs:KeyDescription}} 2014-04-19 12:43 GMT {{Cs:ValueDescription}} 2014-04-19 13:27 GMT
{{Cz:KeyDescription}} - {{Cz:ValueDescription}} -
{{CS:KeyDescription}} - {{CS:ValueDescription}} -
da {{Da:KeyDescription}} 2014-04-19 13:20 GMT {{Da:ValueDescription}} 2014-04-19 11:28 GMT
de {{Template:DE:KeyDescription}} 2014-04-19 12:37 GMT {{Template:DE:ValueDescription}} 2014-04-19 08:00 GMT
{{Template:DE:KeyDescription}} 2014-04-19 12:38 GMT {{Template:DE:ValueDescription}} 2014-04-19 07:57 GMT
el {{El:KeyDescription}} 2014-04-20 18:57 GMT {{El:ValueDescription}} -
en {{KeyDescription}} 2014-04-18 15:35 GMT {{ValueDescription}} 2014-04-14 21:33 GMT
{{KeyDescription no translation}} 2014-04-22 18:18 GMT {{ValueDescription no translation}} 2014-04-22 18:19 GMT
es {{Template:ES:KeyDescription}} 2014-04-19 13:13 GMT {{Template:ES:ValueDescription}} 2014-04-19 11:18 GMT
{{Template:ES:KeyDescription}} 2014-04-19 13:14 GMT {{Template:ES:ValueDescription}} -
fi {{Fi:KeyDescription}} 2014-04-19 13:01 GMT {{Fi:ValueDescription}} 2014-04-09 22:00 GMT
fr {{Template:FR:KeyDescription}} 2014-04-19 12:29 GMT {{Template:FR:ValueDescription}} 2014-04-19 09:20 GMT
{{Template:FR:KeyDescription}} 2014-04-19 12:30 GMT {{Template:FR:ValueDescription}} 2014-04-19 09:18 GMT
FR:KeyDescription - FR:ValueDescription 2014-04-19 16:27 GMT
FR:Template:KeyDescription 2014-04-22 18:10 GMT FR:Template:ValueDescription -
hu {{Hu:KeyDescription}} 2014-04-19 13:43 GMT {{Hu:ValueDescription}} -
it {{Template:IT:KeyDescription}} 2014-04-18 21:26 GMT {{Template:IT:ValueDescription}} -
{{Template:IT:KeyDescription}} 2014-04-18 21:32 GMT {{Template:IT:ValueDescription}} 2014-04-19 11:41 GMT
ja {{Template:JA:KeyDescription}} 2014-04-19 11:08 GMT {{Template:JA:ValueDescription}} -
{{Template:JA:KeyDescription}} 2014-04-19 11:09 GMT {{Template:JA:ValueDescription}} 2014-04-18 21:40 GMT
JA:KeyDescription 2014-04-19 11:12 GMT JA:ValueDescription 2014-04-18 21:42 GMT
lt {{Lt:KeyDescription}} 2014-04-19 14:40 GMT {{Lt:ValueDescription}} -
nl {{Template:NL:KeyDescription}} 2014-04-12 16:53 GMT {{Template:NL:ValueDescription}} 2014-04-19 09:43 GMT
pl {{Pl:KeyDescription}} - {{Pl:ValueDescription}} -
pt {{Pt:KeyDescription}} 2014-04-19 13:32 GMT {{Pt:ValueDescription}} 2014-04-19 13:22 GMT
pt-br {{Pt-br:KeyDescription}} 2014-04-20 16:41 GMT {{Pt-br:ValueDescription}} 2014-04-20 18:56 GMT
ro {{Ro:KeyDescription}} 2014-04-19 14:42 GMT {{Ro:ValueDescription}} -
ru {{Template:RU:KeyDescription}} 2014-04-19 08:54 GMT {{Template:RU:ValueDescription}} 2014-04-19 11:51 GMT
RU:Template:KeyDescription 2014-04-22 18:14 GMT RU:Template:ValueDescription 2014-04-22 18:16 GMT
sv {{Sv:KeyDescription}} 2014-04-19 14:48 GMT {{Sv:ValueDescription}} 2014-04-19 13:51 GMT
uk {{Uk:KeyDescription}} 2014-04-19 13:09 GMT {{Uk:ValueDescription}} 2014-04-19 09:56 GMT
zh-hans {{Zh-hans:KeyDescription}} 2014-04-19 13:46 GMT {{Zh-hans:ValueDescription}} 2014-04-19 13:59 GMT
Key and value description templates
Language Key description template Migrated Value description template Migrated
ar {{Ar:KeyDescription}} yes {{Ar:ValueDescription}} yes
ca {{Ca:KeyDescription}} yes {{Ca:ValueDescription}} .
cs {{Cs:KeyDescription}} yes {{Cs:ValueDescription}} yes
da {{Da:KeyDescription}} yes {{Da:ValueDescription}} yes
de {{Template:DE:KeyDescription}} yes {{Template:DE:ValueDescription}} yes
{{Template:DE:KeyDescription}} yes {{Template:DE:ValueDescription}} yes
el {{El:KeyDescription}} yes {{El:ValueDescription}} .
en {{KeyDescription}} n/a {{ValueDescription}} n/a
{{KeyDescription no translation}} none {{ValueDescription no translation}} none
es {{Template:ES:KeyDescription}} yes {{Template:ES:ValueDescription}} yes
{{Template:ES:KeyDescription}} none {{Template:ES:ValueDescription}} .
fi {{Fi:KeyDescription}} yes {{Fi:ValueDescription}} yes
fr {{Template:FR:KeyDescription}} yes {{Template:FR:ValueDescription}} yes
{{Template:FR:KeyDescription}} yes {{Template:FR:ValueDescription}} yes
FR:KeyDescription . FR:ValueDescription yes
FR:Template:KeyDescription yes FR:Template:ValueDescription .
hu {{Hu:KeyDescription}} yes {{Hu:ValueDescription}} .
it {{Template:IT:KeyDescription}} yes {{Template:IT:ValueDescription}} .
{{Template:IT:KeyDescription}} yes {{Template:IT:ValueDescription}} yes
ja {{Template:JA:KeyDescription}} none {{Template:JA:ValueDescription}} .
{{Template:JA:KeyDescription}} none {{Template:JA:ValueDescription}} yes
JA:KeyDescription yes JA:ValueDescription yes
lt {{Lt:KeyDescription}} yes {{Lt:ValueDescription}} .
nl {{Template:NL:KeyDescription}} yes {{Template:NL:ValueDescription}} yes
pl {{Pl:KeyDescription}} . {{Pl:ValueDescription}} .
pt {{Pt:KeyDescription}} yes {{Pt:ValueDescription}} yes
pt-br {{Pt-br:KeyDescription}} yes {{Pt-br:ValueDescription}} none
ro {{Ro:KeyDescription}} yes {{Ro:ValueDescription}} .
ru {{Template:RU:KeyDescription}} yes {{Template:RU:ValueDescription}} yes
RU:Template:KeyDescription none RU:Template:ValueDescription none
sv {{Sv:KeyDescription}} yes {{Sv:ValueDescription}} yes
uk {{Uk:KeyDescription}} yes {{Uk:ValueDescription}} yes
zh-hans {{Zh-hans:KeyDescription}} yes {{Zh-hans:ValueDescription}} yes