View source for Template:Reflib/Domain doc

{{documentation subpage}}

This is [[Template:Reflib|Reflib]] documentation for article domain librar{{#if: {{{1|}}} | y&#32;'''{{{1|}}}''' | ies}}. It is designed to hold full citations in the [[WP:Manual of Style/Layout#Notes and references|References section]] of an article{{#if: {{{1|}}} | &#32;related to {{#ifexist: {{{1|}}} | [[{{{1|}}}]] | {{{1|}}}}}}} that uses [[WP:SFN|short citations]] in-line. See the [[Template:Reflib#Article domains|article domain table]] for currently supported domains.

== Introduction ==

An '''article domain''' is a topic area in which a group of related articles have shared citations; that is, citations which are used, or are likely to be used, in more than one article in the domain. It is by design a vetted repository of citations to reliable sources where new or veteran editors can come and find useful sources for their topic, already formatted properly as [[Help:CS1|CS1]] or [[Help:CS2|CS2]] citations and ready for use in their article.

{{#if: {{{1|}}} |In the case of domain {{{1|}}}, i|I}}nstead of having to copy and paste full citations among numerous articles {{#if: {{{1|}}} | &#32;related to {{{1|}}} |in the domain}} and keep them in sync, [[Template:Reflib]] allows you to place the citations into {{#if: {{{1|}}} | the | a }} domain container {{#if: {{{1|}}} | for {{{1|}}}{{efn|A '''domain container''' is a repository containing all the shared references for one article domain. This is currently implemented as a subpage of the Reflib template, so '{{NAMESPACE}}:{{BASEPAGENAME}}/{{{1|}}}' for this domain, but this is an internal design decision, and may change.}}}} just once, and then use the template to import needed citations into any articles in the domain that need them. It's up to users to define what constitutes a domain, but as a rough approximation, articles linked from the same [[WP:NAVBOX|navigation template]] are likely to have citations in common that are members of the same article domain{{#ifexist: Template:{{{1|}}} |&semi; see nav box {{tl|{{{1|}}}}} for example}}. [[WP:Categories|Categories]] offer another approach{{#ifexist: Category:{{{1|}}} |&semi; see [[:Category:{{{1|}}}]]}}.

== Usage ==

=== Sections ===

This article domain library is a repository for unique citations which may be used in multiple articles in the {{#if: {{{1|}}} | domain "{{{1|}}}"{{#ifexist: Template:{{{1|}}} |, such as those found in Nav template {{tl|{{{1|French criminal law}}}}}}} | same domain}}. Full citations may be added to this library when they are likely to be used in more than one article: create a new section name that is unique to this page, and add your citation to the section. It does not matter whether or not there is a blank line after the [[MOS:HEADER|section header]]. The section header can be any unique name, and to promote readability of the [[wikicode]] where they are used, it's best to follow the recommendations for [[WP:NAMEDREFS|named footnotes]], such as "Lastname-YYYY". 

Modify as necessary, to make the section header unique on the page. For authors with multiple works in the same year, you may use:  Smith-2004a, Smith-2004b, and so on. If there are several different Smiths, then you may, if you wish, disambiguate with initials of given name(s): SmithA-2004, SmithCJ-2004, SmithM-2004, and so on, but any method that results in a unique section header is acceptable.

If a citation is likely to be used in only one article, there is no need to place it here; just add it to the "Works cited" or "Sources" section as usual.

Please keep sections on the page in alphabetical order, to make it easier to manage, and to more easily spot duplicates. Higher level sections such as letter indexes (A – D; E – J; etc.) are fine, as long as the citation section headers remain unique.

=== Citations ===

Because this is designed to be used with articles that use [[WP:CITESHORT|shortened footnotes]], the citations on the page should use any of the [[Help:CS1|CS1]]- or [[Help:CS2|CS2]]-style templates that create HTML IDs by default suitable for use with [[WP:CITESHORT|shortened footnotes]] using the [[Template:Harvard citation documentation|Harv- and sfn-family templates]]. This includes {{tl|cite book}}, {{tl|cite journal}}, {{tl|cite news}}, {{tl|cite web}}, and any of the other {{tl|citation}} family of templates.

Normally, there should be one citation per section; more than one is not recommended, but if used, will bring in all of the citations in the section. One reason you might do this is when using template {{tl|citec}}/{{tl|harvc}} to specify a number of chapters belonging to the same book; in this case, it is better to keep them all together in one section for simplicity, even if your article doesn't cite each of the chapters. 

The CITEREF generated from the citation (usually by concatenating the values of (all of the) {{para|last''N''}} and {{para|year}}) should be unique, in order to avoid generating a [[Help:Cite errors/Cite error references duplicate key|duplicate target error]].
<includeonly>
== Updating this page ==</includeonly><noinclude>
== Updating domain containers ==</noinclude>

=== Prerequisites ===

It is recommended that only editors experienced in using [[Template:citation|citation templates]] update a domain container. Certain common errors or oversights such as omitting a terminating curly bracket could have repercussions in more than one article, with previously working citations disappearing en masse. Use [[WP:PREVIEW|Preview button]] before saving, to ensure that everything looks good. [[Template:Reflib/Domain_doc#New_domains|Creating a new article domain page]] is low-risk and is encouraged.

=== Adding a new reference section ===

You can add a new reference section at any time, by inserting a new section header and pasting a citation template from an article, or creating a new citation template for it. You can choose any section name that is unique on the page and complies with [[MOS:SECTIONS]], however for ease of use, it is recommended that the section heading reflect the parameters of the {{tl|sfn}} template needed to link to it, namely the last names of the first four authors plus the year, joined with blanks or hyphens, thus: "Doe-2018", or "Masters&nbsp;Johnson&nbsp;1966".{{efn|In CITEREF terms, the optimal section header name is the CITEREF [[Help:Link#What is an "anchor"?|destination anchor]] associated with the citation, minus the 'CITEREF' prefix, and with the concatenated template param values joined with blanks or hyphens. For example, for citation {{tlc|cite book |last1{{=}}Watson |last2{{=}}Crick{{br}}|title{{=}}The Double Helix |year{{=}}1953}} we have citeref 'CITEREFWatsonCrick1953' and recommended section header name "Watson&nbsp;Crick&nbsp;1953" or "Watson-Crick-1953". If param {{para|ref}} is in use, then the CITEREF will reflect that instead, and so should the section name.}} But if you prefer simpler section headings, you can use whatever you want as long as it is unique. [[Template:Reflib/Asea#Pomey-2012|Here]] is an example of a simple section heading for a citation that has three authors; the {{tl|sfn}} still needs to list all three of them (i.e., {{tlc|sfn|Last1|Last2|Last3|{{CURRENTYEAR}}}}), but the section name can be just ''Last1-{{CURRENTYEAR}}'' if it is unique.

If the citation template contains a {{para|ref}} param, such as might be the case when an author has multiple publications in the same year, then it is recommended to use the ref value as the section heading instead. For example, for {{para|ref|<nowiki>{{harvid|Einstein|1905d}}</nowiki>}} tagging his [[Annus mirabilis papers|fourth publication that year]], you could use section header "Einstein-1905d". The section name doesn't *have* to match the template params, that is just a suggestion for most cases; if a mnemonic name better brings to mind what citation is involved, then use that; for example, for Einstein's fourth paper in 1905, you could use a section header of "Einstein special relativity" instead of "Einstein-1905d" if desired. Again, anything unique is an acceptable section name.

Please keep sections in alphabetical order.

=== Use one citation per section ===

Generally speaking, it is recommended that a reference section should contain just one citation. There are exceptions, such as for books containing multiple, independently citable chapters defined by {{tl|citec}} / {{tl|harvc}}, where it may make the most sense to list the book citation via a {{tl|cite book}} first, followed by one or more chapter templates for commonly cited chapters, keeping them all together in one section.{{efn|name="multiple"|For an example of a citation with multiple chapter templates in one section, see {{slink|Template:Reflib/FCL|Tomlinson-1999}}.}} See {{slink||Whitelisting unused chapters}} for how to deal with scripted warnings about uncited chapters that may appear in this case.

=== Adding comments to a section ===

You can add hatnotes, instructions, or other comments to a citation section by including them within paired <code><nowiki><noinclude> ... </noinclude></nowiki></code> tags. Some reasons to do this might be to:
* call attention to similarly named sections, such as at [[Template:Reflib/Asea#Royal-Tusa-2019|Royal-Tusa-2019]]
* give a reminder about how to code a short citation when there are multiple authors, e.g. at [[Template:Reflib/Asea#Pomey-2012|Pomey-2012]]
* provide special instructions, such as when a section has one source with multiple chapters, e.g. at [[Template:Reflib/Asea#Morrison-Gardiner-1995|Morrison-Gardiner-1995]]
* link an open-access, full-text version of the work available on-line; e.g., [[Template:Reflib/Asea#McCarthy-2023|McCarthy-2023]]
* mention a more recent edition of the same title (e.g., [[Template:Reflib/Asea#Morrison-1968|Morrison-1968]]), or a translated work ([[Template:Reflib/Asea#Rougé-1981|Rougé-1981]]), and other reasons.

=== Using Reflib with inline citations ===

It is possible to use  Reflib in an article that uses full inline citation style (instead of [[WP:SFN|short citations]]), as long as the citation in question is alone within its section in the domain container.

=== Renaming or deleting a reference section ===

Renaming a section header of a reference on a library page, or deleting a section containing a reference will cause any articles transcluding those sections via the template to generate an [[:Category:Harv and Sfn template errors#Error messages|sfn "no target" error]] from [[Module:Footnotes]] adjacent to any unlinked [[WP:SFN|sfn]]'s in the References section of the article where the short citations are generated. Before renaming or deleting a section, you should find all the articles that use that section, and update them as needed, using an [[WP:Advanced search|Advanced search]] targeting the section in question. 

Example: if you wish to delete or rename section {{slink|Template:Reflib/{{{1|French criminal law}}}|{{#if: {{{1|}}} | LastName | Bell-2008}}|nopage=yes}}, search for use of that section by going to [[Special:Search]] and pasting this search query: 
: <code><span class="plainlinks">[https://en.wikipedia.org/w/index.php?search=hastemplate%3AReflib+insource%3A%22Bell-2008%22&title=Special:Search&profile=default&fulltext=1 hastemplate:Reflib insource:"{{#if: {{{1|}}} | LastName | Bell-2008}}"]</span></code> 
The search result page will list all articles using that section; these are the articles that will need to be updated if the section is renamed or removed.
<noinclude>
== New domains ==

To define a new domain, start by creating a new domain library page containing section names and citations as described above. Name the page something that is [[WP:NDESC|naturally descriptive]] of the type of citation it will contain. Often, a good name for the library page is one that is the same or similar to the name of the [[WP:NAVBOX|navigation template]] used by articles in the domain. For example, the domain library page for "French criminal law" contains citations likely to be used in articles linked from the nav box {{tl|French criminal law}}. 

:::{{Edit
|1=Template:Reflib/New domain page-{{CURRENTYEAR}}{{CURRENTMONTH}}{{CURRENTDAY2}}-{{CURRENTTIME}}
|2={{Clickable button|{{tooltip|Create new domain page now|This will create a new page at 'Template:Reflib/New domain page-{{CURRENTYEAR}}{{CURRENTMONTH}}{{CURRENTDAY2}}-{{CURRENTTIME}}' preloaded with some useful info. You will have the opportunity to view and modify it before saving.}}|link=no}}
|editintro=Template:Reflib/New domain page instructions
|preload=Template:Reflib/New domain page preload
|tooltip=Click to create 'Template:Reflib/New domain page'<!-- doesn't seem to work -->
}}

Once the new domain library page is saved under its correct name, it is available for immediate use by the template. To enable the shortcut(s), make an [[WP:Edit request]] at the template Talk page to enable the new domain at [[Template:Reflib/decode-lib]]. (As of November 2024, domain library pages live as [[WP:SUBPAGE|subpages]] of the main template, and go live immediately as soon as they are saved. Enabling the domain shortcut requires a template change (addition of a #switch case), but this may change in the future to enable easier configurability and improved [[scalability]].)

You do not need to create a documentation page for your new article domain; documentation is generated on the fly by transcluding this page and passing the domain name.
</noinclude>

== Notes ==
{{notelist}}