Редактирование: Модуль:Sources/doc

{{СИШ}}
{{Рейтинг модуля|p}}
{{Используйте песочницу}}

== Принцип работы модуля ==
Данный модуль генерирует текст, используемый в сносках, ссылающихся на элемент викиданных.

== Тесты ==
{{#invoke: Sources/тесты | run_tests}}

== Служебные подмодули ==
* [[Модуль:Sources/utils]]

== Используемые параметры Викиданных ==
{| class="wikitable"
! scope="col" | Свойство
! scope="col" | Комментарий
|-
| {{WD property|P50}} ||
|-
| {{WD property|P2093}} ||
|-
| {{WD property|P407}} ||
|-
| {{WD property|P364}} ||
|-
| {{WD property|P958}} || используется для указания названия статьи в энциклопедии
|-
| {{WD property|P1476}} || если требуется переопределить название из метки элемента
|-
| {{WD property|P1680}} ||
|-
| {{WD property|P953}} ||
|-
| {{WD property|P1065}} ||
|-
| {{WD property|P854}} ||
|-
| {{WD property|P1433}} ||
|-
| {{WD property|P393}} ||
|-
| {{WD property|P123}} ||
|-
| {{WD property|P291}} ||
|-
| {{WD property|P98}} ||
|-
| {{WD property|P304}} ||
|-
| {{WD property|P1104}} ||
|-
| {{WD property|P478}} ||
|-
| {{WD property|P433}} ||
|-
| {{WD property|P571}} ||
|-
| {{WD property|P577}} ||
|-
| {{WD property|P212}} ||
|-
| {{WD property|P957}} ||
|-
| {{WD property|P236}} ||
|-
| {{WD property|P1545}} ||
|-
| {{WD property|P818}} ||
|-
| {{WD property|P888}} ||
|}

== Функции ==

=== Внешние ===
Внешние функции принимают объекты типа [[mw:Extension:Scribunto/Lua reference manual#Frame%20object|фрейм]] и предназначены для вызова из других модулей или через функцию парсера {{Code|<nowiki>{{#invoke:}}</nowiki>}}.

''Прямое обращение к функциям модулей в статьях крайне нежелательно! Используйте для этих целей подходящие шаблоны.''

==== p.renderSource(''frame'') ====
Выдаёт вики-текст ссылки на заданный источник для подстановки внутрь сноски или списка литературы. См. шаблоны {{Tl|Source}} и {{Tl|ВД-Источник}}, использующие данную функцию''.'' Поддерживает следующие аргументы:

* {{Code|frame.args[1]}} — анонимный аргумент, задающий идентификатор объекта на викиданных, по которому нужно сгенерировать ссылку. Например, [[d:Q20750516|Q20750516]].
* {{Code|frame.args['ref']}} — задаёт метку ''ref'', которую в дальнейшем можно будет использовать в шаблонах типа {{Tl|Sfn}}.
* {{Code|frame.args['ref-year']}} — задаёт метку ''ref-year'', которая используется аналогично метке ''ref''.
* {{Code|frame.args['part']}} — дополнительный аргумент, позволяющий уточнить часть источника, на которую идёт ссылка (например, главу в книге).
* {{Code|frame.args['parturl']}} — ссылка, которую следует поставить на часть, описанную предыдущим аргументом.
* {{Code|frame.args['pages']}} — конкретные страницы в источнике, на которые ведётся ссылка.
* {{Code|frame.args['url']}} — позволяет явно указать, какую ссылку нужно будет проставить на источник.
* {{Code|frame.args['volume']}} — позволяет явно указать том источника, на который идёт ссылка.
* {{Code|frame.args['issue']}} — позволяет явно указать выпуск источника, на который идёт ссылка.

Пробрасывание большей части аргументов происходит в ''[[Модуль:Sources/utils|utils.copyArgsToSnaks]]''. Сам переданный фрейм сохраняется в ''p.currentFrame'' для дальнейшего использования, а на основе переданных аргументов функцией ''artificialSnaks'' создаются искусственные [[d:Wikidata:Glossary|снеки]], которые ссылаются на источник, указанный в {{Code|frame.args[1]}}, через свойства [[d:Property:P248|P248]] (''stated in'') и [[d:Property:P805|P805]] (''statement is subject of''). Затем данные передаются в ''renderReferenceImpl'' для дальнейшей обработки.

==== p.renderReference(''frame, currentEntity, reference'') ====
Выдаёт вики-текст готовой сноски на заданный источник. Поддерживает те же аргументы, что и ''p.renderSource'', кроме ''ref'' и ''ref-year''. См. шаблоны {{Tl|Source-ref}} и {{Tl|ВД-Сноска}}, использующие данную функцию''.'' Также используется в [[Модуль:Wikidata]] для отображения ссылок, указанных возле утверждений на викиданных. Если ''currentEntity'' и ''reference'' отсутствуют, создаются искусственные снеки с помощью функции ''artificialSnaks,'' после чего они передаются в ''renderReferenceImpl''. Если вики-текст для сноски был успешно сгенерирован, он оборачивается в тэг {{Code|<nowiki><ref></nowiki>}} с помощью [[mw:Extension:Scribunto/Lua reference manual#frame:extensionTag|frame: extensionTag]], при этом имя для сноски генерируется путём хеширования её вики-текста через [[mw:Extension:Scribunto/Lua reference manual#mw.hash.hashValue|mw.hash.hashValue]]. Статьи, с такими сносками помещаются в [[:Категория:Википедия:Статьи с источниками из Викиданных]].

=== Внутренние ===

==== tokenizeName(''fullName'') ====
Преобразует полное имя в пару ''{фамилии через пробел, инициалы имён через пробел}''. Реализована в виде разбора случаев, которые можно встретить на викиданных:

# ''Фамилия, Имя''
# ''Фамилия, Имя Имя''
# ''Фамилия Фамилия, Имя''
# ''Имя Имя [[оглы]] Фамилия''
# ''Имя Имя де Фамилия''
# ''Имя … Имя Фамилия'' (хотя бы одно и не более четырёх единичных имён)

Здесь имя, в отличие от фамилии, может являться инициалом. Если ни один из форматов выше не выполнен, возвращает полное имя без изменений.

==== personNameToAuthorName(''fullName'') ====
Преобразует полное имя в формат ''Фамилия И. О.'' с помощью ''tokenizeName''.

==== personNameToResponsibleName(''fullName'') ====
Преобразует полное имя в формат ''И. О. Фамилия'' с помощью ''tokenizeName''.

==== getPeopleAsWikitext(''context, value, options'') ====
Преобразует список имён ''value'' в викитекст в соответствии со списком опций ''options''. В опциях должны быть проставлены следующие поля:

# ''separator'' — разделитель в списке;
# ''conjunction'' — разделитель перед последним элементом списка;
# ''format'' — функция, преобразующая имена к некоторому нормализованному виду (например, ''personNameToAuthorName'');
# ''nolinks'' — логическое значение, должно быть истинным если проставление ссылок нежелательно;
# ''preferids'' — логическое значение, должно быть истинным если нужно вернуть id с викиданных, а не имена.

Если в списке больше ''maxAuthors'' (на текущий момент 10) людей, заменяет остальных на ''и др.'' или его аналоги (если в контексте указан язык, то используется ''i18nEtAl[context.lang]'', иначе используется ''i18nEtAlDefault'').

==== appendProperty(''result, context, src, conjunctor, property, url'') ====
Приписывает ''src[property]'' к ''result'', разделяя их строкой, записанной в ''conjunctor''. Если возможно, оформляет его ссылкой на ''src[url].''

==== generateAuthorLinks(''context, src'') ====
Возвращает список авторов ''src.author'', оформленный через ''getPeopleAsWikitext'' и обрамлённый в {{Code|<nowiki><i class="wef_low_priority_links"></i></nowiki>}}''.''

==== appendTitle(''result, context, src'') ====
Дописывает к ''result'' строку {{Code|src.part // src.title}} либо только {{Code|src.title}} если ''src.part'' не указан. Если возможно, обрамляет ''src.part'' (или ''src.title'' если ''src.part'' не указан) в ''src.url''.

==== appendLanguage(''result, context, src'') ====
Если ''context.lang'' отличается от ''i18nDefaultLanguage'' (в нашем разделе русский), то указание об этом приписывается к ''result'' с помощью [[Модуль:Languages]] в формате {{Tl|ref-lang}}.

==== appendSubtitle(''result, context, src'') ====
Дописывает к ''result'' строку {{Code|: src.subtitle}} если ''src.subtitle'' определён.

==== appendOriginalTitle(''result, context, src'') ====
Дописывает к ''result'' строку {{Code|1=&nbsp;= src.originaltitle}} если ''src.originaltitle'' определён.

==== appendPublication(''result, context, src'') ====
Дописывает к ''result'' строку {{Code|&nbsp;// src.publication: src.publication.subtitle}} если определён ''src.publication.subtitle'', либо {{Code|&nbsp;// src.publication}} если определён только ''src.publication''.

==== appendEditor(''result, context, src'') ====
Дописывает к ''result'' строку {{Code|&nbsp;/ prefix src.editor}} если определён ''src.editor'', где ''prefix'' определяется по ''context.lang'' (по умолчанию, {{Code|под ред.}}).

==== appendEdition(''result, context, src'') ====
Дописывает к ''result'' строку {{Code|&nbsp;— src.edition}} если ''src.edition'' определён.

==== appendPublicationData(''result, context, src'') ====
Добавляет к ''result'' строку вида {{Code|&nbsp;— src.place: src.publisher, src.year.}} если хотя бы один из указанных параметров определён. Неуказанная часть опускается вместе с соответствующей пунктуацией. В частности, двоеточие ставится только если указано ''src.place'' и хотя бы что-то из ''src.publisher'' и ''src.year'', запятая ставится только если указаны и ''src.publisher'', и ''src.year''. Тире и точка ставятся если указан хотя бы один из параметров.

==== appendVolumeAndIssue(''result, context, src'') ====
Добавляет к ''result'' строку виду {{Code|&nbsp;— letter_vol src.volume, letter_iss src.issue.}} если хотя бы один из указанных параметров определён. Запятая ставится если указаны оба параметра. ''letter_vol'' и ''letter_iss'' определяются по ''context.lang'' (например, {{Code|Т.}} и {{Code|вып.}} для русских текстов, {{Code|Vol.}} и {{Code|Iss.}} для английских).

==== appendPages(''result, context, src'') ====
Добавляет к ''result'' строку вида {{Code|&nbsp;— letter src.pages.}} если ''src.pages'' определён, при этом в качестве разделителя в ''src.pages'', если это диапозон страниц, используется символ «—», а ''letter'' определяется исходя из ''context.lang'' (например, {{Code|P.}} для английского и {{Code|С.}} для русского).

==== appendNumberOfPages(''result, context, src'') ====
Добавляет к ''result'' строку вида {{Code|&nbsp;— src.numberOfPages letter}} если ''src.numberOfPages'' определён. При этом ''letter'' определяется из ''context.lang'' ({{Code|p.}} для английского и {{Code|с.}} для русского).

==== appendBookSeries(''result, context, src'') ====
Добавляет к ''result'' строку вида {{Code|&nbsp;— (src.bookSeries; letter_vol src.bookSeriesVolume, letter_iss src.bookSeriesIssue)}} если ''src.bookSeries'' определено. Точка с запятой ставится только если определено ''src.bookSeriesVolume'' или ''src.bookSeriesIssue'', запятая ставится если определены оба параметра. ''letter_vol'' и ''letter_iss'' определяются из ''context.lang'', аналогично тому, как это делается в ''appendVolumeAndIssue''.

==== appendBookSeries(''result, context, src'') ====
Добавляет к ''result'' информацию из ''src.tirage'' если тот определён. Формат определяется из ''context.lang'', для английского это {{Code|&nbsp;— ed. size: src.tirage}}, а для русского {{Code|&nbsp;— src.tirage экз.}}.

==== appendIdentifiers(''result, context, src'') ====
Добавляет к ''result'' идентификаторы [[ISBN]], [[ISSN]], [[Doi|DOI]], [[PMID]] и [[ArXiv.org|arXiv]] если те определены. Идентификаторы приписываются через тире, более точный формат определён в таблицах ''options_commas'', ''options_issn'', ''options_doi'', ''options_pmid'' и ''options_arxiv''.

==== appendSourceId(''result, context, src'') ====
Оборачивает ''result'' в {{Code|<nowiki><span class="wikidata_cite citetype" data-entity-id="src.sourceId"></span></nowiki>}}, где ''citetyle'' это ''src.type'' если это поле определено и ''citetype_unknown'' в противном случае.

==== appendAccessDate(''result, context, src'') ====
Добавляет к ''result'' строку виду {{Code|<small>Проверено dd month yyyy.</small>}}, где ''dd'', ''month'' и ''yyyy'' берутся из ''src.accessdate'' если данное поле определено.

==== populateUrl(''context, src'') ====
Если ''src.url'' не определено, но ''src.sourceId'' известен, пытается присвоить в ''src.url'' ссылку на [[Викитека|викитеку]].

==== populateYear(''src'') ====
Если ''src.year'' не определён, пытается заполнить его из ''src.dateOfPublication'' и ''src.dateOfCreation''.

==== populateTitle(''src'') ====
Если ''src.title'' не определён, пытается присвоить ему ''src.url'', если и это не получается, то присваивает {{Code|''(unspecified title)''}}.

==== renderSource(''context, src'') ====
Внутренняя функция, генерирующая текст, который будет отображаться в сноске. Действует следующим образом:

# Записывает ''src.lang'' в ''context.lang'' (или ''i18nDefaultLanguage'' если ''src.lang'' записать не получилось).
# Вызывает ''populateUrl'', ''populateTitle'' и ''populateYear''.
# Заводит переменную ''result'', изначально равную ''generateAuthorLinks(context, src)''.
# .Последовательно применяет к ''result'' функции ''appendTitle—appendAccessDate'', при этом блок ''appendEditor—appendAccessDate'' дополнительно обрамляется в {{Code|<nowiki><span class="wef_low_priority_links"></span></nowiki>}}
<noinclude>
[[Категория:Модули:Документация]]
</noinclude>