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

{{СИШ}}
{{module rating|p}}
{{Используйте песочницу}}

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

== Функции ==

=== Внешние ===
Внешние функции принимают объекты типа [[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>}}

==== '''artificialSnaks('''''args''''')''' ====
Создаёт искусственные [[d:Wikidata:Glossary|снеки]], которые ссылаются на источник с идентификатором ''frame.args[1]'' через свойства [[d:Property:P248|P248]] (''stated in'') и [[d:Property:P805|P805]] (''statement is subject of''), а также пробрасывает в них аргументы (том, выпуск и т. д.).

== Служебные подмодули ==

* [[Модуль:Sources-utils]]
* [[Модуль:Sources-authors]] (не используется)

== Используемые параметры Тептарданных ==
{| class="standard"
! Свойство !! Комментарий
|-
| {{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}} ||
|}

== Тесты [ [//ru.wikipedia.org/w/index.php?title=Модуль:Sources/тесты&action=edit править] ] ==
<includeonly>
{{#invoke: Sources/тесты | run_tests}}
</includeonly><noinclude>
[[Категория:Модули:Документация]]</noinclude>