Из Википедии, бесплатной энциклопедии
Перейти к навигации Перейти к поиску

Шаблоны - очень мощная функция MediaWiki , но они могут сбивать с толку новых пользователей, и даже опытные пользователи могут испытывать трудности с пониманием более сложных. Поэтому шаблоны должны сопровождаться документацией для повышения удобства использования.

Документация по шаблону должна объяснять, что делает шаблон и как его использовать. Он должен быть достаточно простым, чтобы пользователь, не обладающий полным знанием тонкостей синтаксиса шаблонов, в том числе много опытных участников, сосредоточивших свое внимание на чем-то другом, мог правильно его использовать. Это особенно верно в случае очень широко используемых шаблонов.

Редакторы должны придерживаться официальных политик или руководящих принципов, когда страницы документации по шаблонам не соответствуют установленным стандартам и принципам сообщества. Редакторам также следует избегать цитирования страниц документации по шаблонам, как если бы они были политикой, включая это практическое руководство . Страницы документации по шаблонам могут быть написаны без особых - если они вообще есть - дебатов, в отличие от политик Википедии, которые были тщательно проверены сообществом (подробности см. В WP: Local Connsus ).

Что включить

Документация по шаблону должна охватывать:

  • Основная цель шаблона: что он делает , и если это не сразу видно, почему это должно быть сделано. Если есть другие шаблоны с похожими названиями или назначениями, их стоит упомянуть, чтобы снизить вероятность использования неправильного. Включите важные ограничения , такие как отсутствие {{ видимости Navbox }} на мобильном веб-сайте, если шаблон должен использоваться только для определенных стран или периодов времени, или другие вещи, которые редакторы должны знать, прежде чем использовать шаблон.
  • В параметрах шаблона: являются ли они пронумерованы, по имени или по желанию, и если да, то какие значения по умолчанию , и какое влияние они имеют. Если параметр может принимать только ограниченный набор значений или каким-либо образом ограничен, например, если он может использовать только «да», «нет» или число, это следует четко объяснить.
  • Примеры использования : укажите точный викитекст, который следует использовать, и результат, который он дает. Вики-текст можно заключить в <code>...</code>контейнер, чтобы он был понятен и easy to copy, like this. Если шаблон можно использовать по-разному, например, с необязательными параметрами или без них, приведите ряд примеров. Хороший способ сделать это - несколько раз включить сам шаблон в документацию (т. Е. Использовать живые примеры) с разными параметрами каждый раз и перечислить параметры, используемые в каждом случае. С Template: Xpd это можно сделать без двойного вызова шаблона в викитексте.
  • Теги TemplateData : см. Wikipedia: TemplateData / Tutorial .
  • Связанные шаблоны : если шаблон является одним из серии шаблонов, включите ссылки на них - в частности, убедитесь, что каждый шаблон в серии связан с каждым из других, так как это упрощает навигацию. (Для этой цели может быть полезен отдельный шаблон навигации, см .: Шаблон: шаблоны защиты ).
  • Категории, где это применимо ( ссылки InterWikimedia должны быть указаны в Викиданных - дополнительная информация в Википедии: Викиданные ). Как и документация, категории должны быть перечислены в<noinclude>...</noinclude>контейнере в шаблоне или в<includeonly>{{Sandbox other||...}}</includeonly>тегах, если они размещены на странице документации. Доступно множество категорий шаблонов, см .: Категория: шаблоны Википедии для их просмотра.

Английская Википедия - это источник шаблонов для сотен других Википедий и родственных проектов. Часто шаблоны полностью автономны, поэтому процесс прост: содержимое просто копируется на новую страницу шаблона в другой вики, и все работает. Однако в более сложных шаблонах шаблон может вызывать модуль, включать другие шаблоны, работать только в паре с отдельным шаблоном или требовать для работы определенного кода CSS или Javascript. В этих случаях полезно включить краткий список шаблонов или другого кода, который требуется для этого, в конце документации.

Где разместить

Страница шаблона в пространстве имен Template - это место для кода шаблона, который управляет внешним видом и поведением этого шаблона. То, что обычно появляется под заголовком на обработанной странице Template: (в отличие от окна редактирования на вкладке Edit или, в случае шаблонов, код которых защищен, на вкладке View source , это сам визуализированный шаблон, за которым следует отдельный раздел, чтобы отобразить созданную для шаблона документацию, за которой следуют категории, к которым принадлежит шаблон.

Тем не менее, редактируемые вики - документация шаблона часто размещают на отдельный субстранице самого шаблона, который затем включен через в конце страницы шаблона. Это отделяет часто сложный код шаблона от документации, упрощая редактирование документации и уменьшая количество случайных ошибок редактирования в коде шаблона. Это также позволяет защищать шаблоны там, где это необходимо, ограничивая доступ к редактированию кода важных шаблонов, в то же время позволяя любому редактировать документацию этих шаблонов. Этот метод иногда называют «шаблоном страницы шаблон-документ».

Любая документация на странице шаблона (включая TemplateData ) всегда должна быть заключена в <noinclude>...</noinclude>контейнер, чтобы она не отображалась, когда шаблон используется на другой странице.

Как создать подстраницу документации

Поместите документацию в шаблон

При создании (публикации) шаблона необходимо указать {{ documentation }}. Затем создается страница документации со [view] [edit] [history] [purge]ссылками. Вы можете создавать и редактировать документацию по шаблону, щелкнув [edit]ссылку на этой панели .

Подстраницы документации по шаблонам, использующие {{ documentation }}, именуются и форматируются с использованием следующего общего шаблона для единообразия.

Предположим, ваш шаблон назван Template:X. Отредактируйте шаблон и добавьте следующее в конец кода шаблона или используйте {{subst: doc-code }}:

[--последняя строка кода вашего шаблона -] <noinclude>{{Документация}}<! - Добавляйте категории на подстраницу / doc и интервики в Викиданные, а не здесь! -></noinclude>

Это включит {{ документацию }} внизу страницы шаблона.

Важно : убедитесь, что открытие <noinclude>начинается сразу после последнего символа кода или текста шаблона, а не с новой строки или каких-либо промежуточных пробелов. В противном случае при его использовании под шаблоном будет вставлено дополнительное пространство, что обычно нежелательно.

Если шаблон уже защищен, попросите администратора сделать это или запросите изменение, используя на странице обсуждения шаблона. Если документация и категории уже существуют в разделе, заключенном в контейнер, переместите их на подстраницу документации (где они должны быть заключены ), так как лучше не разделять документацию на две отдельные страницы.{{edit protected}}<noinclude>...</noinclude><includeonly>...</includeonly>

Автоматическое создание

Используйте [create]ссылку внизу пустого поля документации, чтобы автоматически создать предварительно загруженную подстраницу документации. Вставьте документацию после верхней строки и категории под соответствующей строкой комментария - оставив комментарий на месте, чтобы макет сохранялся при редактировании страницы в будущем. Связанные шаблоны, страницу политики, проекты и т. Д. Можно связать, добавив раздел «См. Также». Сохраните подстраницу.

Ручное создание

Чтобы создать подстраницу документации вручную, создайте подстраницу с именем Template:X/doc. См. Подробности на {{ подстранице документации }} или начните страницу, скопировав следующий стандартный викитекст:

{{ Подстраница документации  }} <! - Добавьте категории, указанные внизу этой страницы, и интервики в Викиданные ->== Использование ==<includeonly> {{ другая песочница  || <! - Категории под этой строкой ; интервики в Викиданных ->        }} </includeonly>

В верхней строке отобразится сообщение с объяснением текущей страницы и ссылка на страницу шаблона. Сохраните подстраницу и следуйте инструкциям в разделе « Использовать шаблон: документация ».

С TemplateData

Вместо того, чтобы вручную писать лид-граф и таблицу использования, большую часть работы может выполнить шаблон {{ Format TemplateData }}. Просто напишите ваши TemplateData в интерфейсе таблицы, а затем оберните их в вызов шаблона, как {{Format TemplateData|1=<templatedata>...</templatedata>}}в верхней части страницы.

Заметки

Вы можете перенаправить страницу обсуждения подстраницы / doc на страницу обсуждения самого шаблона. Тогда все разговоры, связанные с шаблоном и его документацией, попадут на одну и ту же страницу обсуждения. Например, перенаправить Template talk:X/docна Template talk:X.

Страницу документации также можно перенаправить на подстраницу / doc другого шаблона, если это касается использования обоих шаблонов. В этом случае щелчок по ссылкам для просмотра или редактирования документации напрямую откроет цель перенаправления. Если необходимо получить доступ к самому перенаправлению (например, чтобы удалить перенаправление и создать отдельную страницу документа), перейдите по URL-адресу шаблона, щелкнув адресную строку в верхней части браузера, и добавьте / doc в конце.

Пустой

Чтобы создать пустой шаблон, который затем можно скопировать из документации и вставить на другую страницу, используйте:

{{subst:#tag:pre|{{subst:Parameters|code|base={{subst:BASEPAGENAME}}}}|style=overflow: auto;}}

Примеры

Чтобы сгенерировать экземпляр шаблона, заполненный его собственными именами свойств, используйте:

{{subst:Parameters|demo|base={{subst:BASEPAGENAME}}|_base=}}

Категории и межвики-ссылки

  • Чтобы поместить сам шаблон в категорию , добавьте [[Category:Category name]]код в <includeonly>...</includeonly>раздел на подстранице документа .
  • Чтобы создать межвики-ссылку для самого шаблона , перейдите в Викиданные и следуйте инструкциям по добавлению ссылок на страницы.
  • Чтобы поместить подстраницу документа в категорию , добавьте [[Category:Category name]]код в <noinclude>...</noinclude>раздел на подстранице документа .
  • Чтобы шаблон помещал статью в категорию (если статья включает шаблон), добавьте [[Category:Category name]]код в <includeonly>...</includeonly>раздел на странице шаблона. Точное размещение в коде шаблона может повлиять на выполнение кода категории.

/ песочница и / testcases

Перед внесением изменений в шаблон может быть полезно сначала скопировать код шаблона в песочницу и запустить несколько тестов, поскольку шаблон может быть виден на тысячах или даже миллионах страниц. Если вы создаете подстраницы с точными именами « / sandbox » и « / testcases » для шаблона, тогда зеленый {{documentation}}прямоугольник в шаблоне автоматически определяет это и будет показывать ссылки на эти страницы в своем заголовке. См. « Википедия: песочница шаблонов и тестовые примеры» для получения дополнительной информации.

Несколько шаблонов, одна страница документации

Когда несколько шаблонов работают вместе или очень похожи, часто проще и понятнее поддерживать одну единую страницу документации, которая документирует их вместе. Самый простой способ сделать это - создать полную страницу документации для одного из шаблонов, а затем выполнить «мягкие перенаправления» из других шаблонов. См., Например: {{ wrap }}.

Непосредственно на странице шаблона

Если подстраница документации не была создана, а шаблон {{ documentation }} используется с |content=параметром на фактической странице шаблона, тогда, чтобы поместить сам шаблон в категорию, добавьте [[Category:Category name]]внутри шаблона документации после содержимого. Например, для размещения на актуальной странице шаблона:

<! - Последняя строка кода вашего шаблона -> <noinclude> {{ Документация  |  content  = <! -  документация по шаблону  -> [[ Категория : Категория  Название ]] [[ Категория : Категория  name2 ]] }} </ noinclude>

Когда не нужна документация

Если отображаемый шаблон будет ссылаться на страницу, которая может служить документацией, тогда отдельная документация будет излишней, и ее не нужно создавать. Например, шаблон-заглушка, использующий шаблон {{ asbox }} в качестве основы, уже будет отображать предварительно загруженную общую документацию для всех шаблонов-заглушек, использующих этот шаблон, и не будет нуждаться в дополнительной документации.

Секреты и уловки

Вот несколько советов, которые помогут облегчить написание документации:

  • Ссылки на шаблоны, например {{ Японский год | 1800}}, можно вставить, написав {{ tlp | Японский год | 1800}} . Похожие шаблоны см. В {{ tlp }}.
  • HTML-теги, например, <ref group="note">...</ref>можно легко вставить с помощью {{ tag }}. Этот пример записывается как {{ tag | ref | params = group = "note"}}.
  • Знак равенства = можно вставить с помощью {{=}} . Например, {{ Требуется цитата | date = 1900-02-29}} создается с помощью {{ tlp | Требуется цитата | date {{=}} 1900-02-29}} . Избегайте эквивалентного обозначения & # 61; который непросто прочитать другим редакторам.
  • Не забывайте об одном <nowiki />теге. [[ <nowiki />пример]] становится [[пример]], а [ <nowiki />http://en.wikipedia.org без ссылки] становится [ http://en.wikipedia.org без ссылки]. См. WP: NOWIKI для подробностей.
  • Для ссылки на категорию используйте {{ cat }}. Например, {{ cat | Шаблоны с неправильным синтаксисом параметра}} становится Категория: Шаблоны с неправильным синтаксисом параметра .
  • Чтобы запретить категоризацию страниц / sandbox и / testcases шаблона (если они существуют), используйте этот код внизу подстраницы документации:
<includeonly> {{ другая песочница  || {{ другие тесты || <! - Категории ниже этой строки , пожалуйста ; интервики в Викиданных ->          }}}} </includeonly>
  • Когда шаблон является дочерним информационным блоком , документация кажется неработающей. Предотвратите это, добавив тег <includeonly>:
{{Некий шаблон инфобокса (дочерний)| child = <includeonly> да </includeonly>| label1 = Привет| data1 = Мир}} <noinclude> {{документация}} </noinclude>

Смотрите также

  • {{ Documentation }} - включает документацию на страницу шаблона и предоставляет ссылки на просмотр, редактирование и историю документации.
  • {{Дополнительная страница документации }} - поясняет, что далее следует документация, и ссылается на задокументированную страницу.
  • <noinclude> а также <includeonly>
  • {{ Улучшение документации }}
  • {{ Tag }} - глобальное использование
  • {{ Список ссылок на шаблоны }}
  • {{ WPBannerDoc }} - для шаблонов WikiProject
  • Википедия: шаблоны высокого риска
  • Википедия: песочница шаблонов и тестовые примеры