Template:Reflib/Domain doc

This is Reflib documentation for article domain libraries. It is designed to hold full citations in the References section of an article that uses short citations in-line. See the 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 CS1 or CS2 citations and ready for use in their article.

Instead of having to copy and paste full citations among numerous articles in the domain and keep them in sync, Template:Reflib allows you to place the citations into a domain container 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 navigation template are likely to have citations in common that are members of the same article domain. Categories offer another approach.

Usage

Sections

This article domain library is a repository for unique citations which may be used in multiple articles in the 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 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 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 shortened footnotes, the citations on the page should use any of the CS1- or CS2-style templates that create HTML IDs by default suitable for use with shortened footnotes using the Harv- and sfn-family templates. This includes {{cite book}}, {{cite journal}}, {{cite news}}, {{cite web}}, and any of the other {{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 {{citec}}/{{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) |lastN= and |year=) should be unique, in order to avoid generating a duplicate target error.

Updating domain containers

Prerequisites

It is recommended that only editors experienced in using 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 Preview button before saving, to ensure that everything looks good. 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 {{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 Johnson 1966".

If the citation template contains a |ref= param, such as might be the case when an author has multiple publications in the same year, then use its value instead; for example, for |ref=Einstein1905d tagging his 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.

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 {{citec}} / {{harvc}}, where it may make the most sense to list the book citation via a {{cite book}} first, followed by one or more chapter templates for commonly cited chapters, keeping them all together in one section. See § Whitelisting unused chapters for how to deal with scripted warnings about uncited chapters that may appear in this case. It is possible to use Reflib in an article that uses full inline citation style, 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 sfn "no target" error from Module:Footnotes adjacent to any unlinked 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 Advanced search targeting the section in question.

Example: if you wish to delete or rename section § Bell-2008, search for use of that section by going to Special:Search and pasting this search query:

hastemplate:Reflib insource:"Bell-2008"

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.

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 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 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 {{French criminal law}}.

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 December 2023, domain library pages live as 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.