Skip to content

Latest commit

 

History

History
123 lines (100 loc) · 6.95 KB

CONTRIBUTING.md

File metadata and controls

123 lines (100 loc) · 6.95 KB
Raw

Порядок следования (комбо) полей в экранных формах

Важно для единообразия с встроенными заготовками JOSM.

  • shop/amenity (любые top-level теги),
  • name,
  • name:ru/:en,
  • official_name,
  • brand,
  • contact:website,
  • contact:phone,
  • opening_hours,
  • level,
  • operator

Максимально возможное использование и переиспользование шаблонов (chunk)

Для примера можно посмотреть, как используются шаблоны в встроенной заготовке.

Хоть современные текстовые редакторы и позволяют сделать очень гибко и очень быстро замену одного текста на другой. Но зачем менять наименование поля в 50 строках (и обязательно изменить его там, где не следовало бы), когда можно изменить один раз в шаблоне?

Это именно то, для чего шаблоны и придуманы!

Сортировка

Идея в том, чтобы при включенной сортировке в самом JOSM порядок групп и пунктов меню не изменялся.

Сама сортировка:

  1. Пункты меню группируются в подгруппы:
    1. числа: 36,6
    2. англоязычные: CMD, Subway, IL Патио
    3. русскоязычные
  2. Внутри групп сортировка по алфавиту: 0-9, A-z, А-я
  3. Если имеются названия на разных языках, то в приоритете сортировка по русскоязычному:
    Domino’s Pizza/Домино’c Пицца должна быть отсортирована по Домино’c Пицца

Групп меню

  1. Остальные группы
  2. <разделитель>
  3. Госорганы, медицина, образование
  4. <разделитель>
  5. Городские сущности

Пунктов внутри группы

Согласно общим правилам — по алфавиту.

Тегов внутри пункта

Общий принцип тот же. Если порядок не важен, то сортируется по алфавиту.

Пустая строка в начале:

<item ... >
  <space />

Набор полей, которые будут доступны для ввода на экранной форме. В том порядке, в котором должны быть на экране:

  <combo ... />
  <reference ... />
  <text ... />

Набор тегов, который заполняется без возможности изменения:

  <key ... />
  ...
  <key ... />

Ссылки и шаблоны, в которых обычно напиханы поля, что выводятся внизу экранной формы:

  <link ..." />
  <reference ref="level_wheelchair_address_wifi_outdoorseating_drivethrough" />
</item>

Атрибутов внутри тега

  1. key/ref
  2. text/name
  3. ru.text/ru.name
  4. values/value
  5. ru.display_values
  6. default
  7. type
  8. preset_name_label
  9. name_context
  10. icon

Комментарии внутри файла

Если есть необходимость, если это добавит удобства или будет полезно — комментируйте.

Два основных подхода

  1. В той же строке
  2. Над блоком кода

Первый подход используется в встроенной заготовке на конкретных элементах, например пунктах меню — <item> — или группах меню. Комментарий ставится в конце строки с закрывающим тегом </item>. Добавляет удобства, когда в редакторе теги свёрнуты.

Второй — когда ниже идёт группа элементов, объединённых по смыслу. Например, все чанки связанные с временем работы заведений.

Детализация комментария

Для того, чтобы обозначить комментарий как то, что нужно сделать, используйте <!-- TODO: ваш текст -->
Для того, чтобы обозначить комментарий, на который нужно обратить внимание, используйте <!-- NB: ваш текст -->

Некоторые текстовые редакторы (например, atom) подсвечивают такие комменатрии.

El clasico

Если есть потребность "выключить" кусок кода, но не хочется потерять информацию из него, такой кусок можно просто закомментировать. Но не стоит злоупотреблять этим, чтобы не захламлять код мусором. В конце концов это гитхаб, тут хранится история изменений.

По мере обрастания уверенностью, что закомментированный код не пригодится, вычищайте такие куски.

Прочее

Основной язык заготовок — английский

Удивительно, правда?

Можно считать, что исторически так сложилось. Хотя особой причины для этого нет. Но, раз так, то у всего, где есть текстовое описание, хорошо бы в атрибуты вида name, text, display_values и т.п. заносить текст на английском языке. Если такого (например, названия у магазина) не сущесвтует — транслитерировать/транскрибировать.

Отступы слева отбиваются пробелами, а не табуляцией

Пробел или нет в конце тега?

Если тег не закрывается в той же строке, то пробелом не отбивается:

<item name="L'etoile">
</item>

Если тег закрывается в той же строке, то отбивается:

<space />
<key value="Л'Этуаль" />