Wikipedia:Substitution
This page documents an English Wikipedia editing guideline. Editors should generally follow it, though exceptions may apply. Substantive edits to this page should reflect consensus. When in doubt, discuss first on this guideline's talk page. |
This page lists templates that should always be substituted except in the Wikipedia namespace. Automated tools (bots) which do such replacements will never be used on the original template pages.
If you are going to use a bot to substitute templates, please read through the talk page first, as many are under dispute or change status over time, and substitution is permanent.
About subst
Definition
The subst: keyword (short for "substitution") is used as a prefix inside template code. It changes the way the software expands the template. Ordinarily, a template will be expanded "on the fly"; that is, the template code calls a separate page for the text every time someone edits a page it is used on. Placing "subst:" inside the curly brackets tells the software to permanently substitute the template with text of the template (that is, the text that is on the template's article page when the template is added to the page). Therefore {{template}} becomes {{subst:template}} and the full text is expanded when you save the page and does not change even if the template is edited.
Usage
You can subst a template tag by adding "subst:" to a template tag. For example, use {{subst:test5}} instead of {{test5}}. When this is a major component of an edit, it is strongly suggested that the template be mentioned in the edit summary (for instance, put "{{subst:test}}" or "test1 applied" in your edit summary so other editors can easily see what you have done). Additionally, when creating or editing templates that are commonly substituted, adding an HTML comment to the template page helps article editors to see how templates are being used (e.g. <!-- Substituted from Template:Doctl -->
).
Benefits of substitution
- Templates are often modified or deleted. If a template is boilerplate text, consider whether you want it to vary as the template is improved. If your answer is "no", substitution is warranted. An example of this is the {{welcome}} template. The archives of a user's talk page should show the actual welcome message they received, not the current welcome message.
- If there is a template you would like to modify for a single occasion, but you do not want to modify the template for all the pages that use it, and you do not want to make a new template, you can substitute the template and then with a second edit, make the modifications. For example: a template might be used with all the states in the United States and the District of Columbia. The template might be worded correctly for the states, but not for DC. To fix the wording, you can substitute the template and then fix the wording.
- Substituting frequently used, but unprotected templates (of which there are few) limits the damage that can be caused by vandalising them. See high-risk templates.
- Using certain templates hides wikitext from newcomers, which prevents them from learning how to use it. (Of course, there is a "how to edit" link at the bottom of each edit page.)
- Substituting en masse may speed up the site, though the amount and significance of this is the subject of frequent debate. Every time a page is modified, the server must get text from a separate page for every template used. Although each individual template has little effect, the vast number of templates used on Wikipedia is one factor affecting server load and article load times. Chief Technical Officer Brion Vibber (who "maintain[s] overall responsibility for all technical functions of the Foundation, including both hardware and software") has said: "'Policy' should not really concern itself with server load except in the most extreme of cases; keeping things tuned to provide what the user base needs is our job." (See Wikipedia:Don't worry about performance.)
- See Wikipedia:Transclusion costs and benefits for further details.
Drawbacks of substitution
- Once a template is substituted, the result is no longer linked to the template, making it hard to find all pages displaying that text (though categories can sometimes relieve this). This problem can easily be worked around by including a link to the template in the template's code.
- A substituted template will not be updated when the master template is updated.
- If the template is used to standardize the appearance of something, you probably do not want to do a substitution. An example of this is a table of contents or navigation box.
- Substituting en masse — editing thousands of articles with bots — slows down the site and wastes server resources unnecessarily.
- Substitution increases the size of articles in the database and database dumps.
- A substituted template can add a lot of wiki-code or HTML to the article, harming accessibility for the less technically inclined.
- Substituting templates prevents newcomers from learning to use templates, and prevents users from finding their documentation.
- When a user tries to copy, for example, the warnings for vandaloids created by the templates described at Template:Test, from an existing page to another page where it is needed, that user receives no clue that the content on the existing page was created by a template! If the template has changed recently, then the user might find several undated versions of each warning. The user is left wondering what to do. It looks like each editor copies or makes their own warnings. Which version to use? Write my own? This whole 'subst' feature is weird,
- If the template is just being used temporarily, it is usually better not to substitute. Substituted templates are much harder to remove or modify.
- When a vandalised template is substituted, it is more difficult to repair than regular vandalism because of the lack of links between the template and its incarnations and the lack of updatability.
- Unsubstituted deletion tags for trivial pages (such as categories and redirects) offer the deleting administrator a convenient, meaningful deletion summary. Example:
"content was: '{{rfd}} #REDIRECT Wikipedia' (and the only contributor was 'Jimbo Wales')".
A precise deletion comment gives onlookers (especially non-administrators unable to view the deleted edits) better insight as to why a specific item may have been deleted. If templates such as {{rfd}}, {{cfr}}, etc. are substituted, the "reason for deletion" field defaults to a blank line. However, pages deleted via {{afd}} and {{mfd}} should be deleted with a link to the subpage where the deletion was discussed.
Templates that should be substituted
This is a list of templates that should always be substituted, organised by namespace. Each list is ordered alphabetically with grouped series.
Article namespace
- camden noir (Author)
- {{footnotes}}, {{Footnotestext}} — substituting these inserts a commentary only visible in edit mode, with a short explanation of how footnotes work (the first also inserts the <references/> tag),
- {{lived}} — shortcut used to add birth/death categories to biographical articles
- {{prettytable}}, {{Prettytable-center}}, {{Prettytable95}}, {{Prettytable100}}, {{Prettytable100center}}, {{Prettyinfobox}}, {{PrettytableN}}, {{Prettytablewidth}}, {{F1 race table}}, {{Prettytable-center2}}
- {{sub}}, {{sup}} – but suggest these not subst:ed if used many times on one page, otherwise code likely to become cluttered.
Article talk
User talk namespace
All of the templates listed in Category:User warning templates should be substituted.
Image namespace
- {{Album Image}} — simple code, uses {{Non-free album cover}}.
Deletion-process documentation
- {{afd bottom}}, {{afd top}}
- {{mfd top}}, {{mfd bottom}},
- {{mfd}}
Misc. templates
- {{debate top}}, {{debate bottom}} — similar boilerplate message as for the deletion related messages, but for regular discussions instead.
- {{Nowrap}} used to ensure that wikilinks do not break across lines
- {{TFAfooter}} links relevant to current featured article, notably used on the main page.
- User signature templates cause undue server strain as changes to a minor user template must then be widely propagated.
- {{WP:RM}}, {{Move2}} simplify move requests.
Uncategorised suggestions
Templates that must be substituted
These templates have a purpose and/or syntax that require them to be substituted.
- {{afd}} — or else the link to "this article's entry" does not work.
- {{archivebox}} — subst magic. Creates a link box for archives.
- {{conv-dist}} — Produces text converting an input distance to different units
- {{conv-temp}} — Produces text converting an input temperature to different units
- {{doctl}} — must be substituted in order to function; creates standard form on template talk page for manual editing.
- {{nld}} — For images with no info on copyright status, adds {{no license}} with today's date automatically filled in.
- {{NoMoreLinks}} - For "External links" section of frequently spammed articles.
- {{nrd}} — For images with no fair use rationale, adds {{no rationale}} with today's date automatically filled in.
- {{nsd}} — For images with no source info, adds {{no source}} with today's date automatically filled in.
- {{orfud}} — For "generic" orphaned fair use images, adds {{orphaned fairuse not replaced}} with today's date automatically filled in.
- {{or-fu-re}} — For fair use images that have been orphaned in favour of another image, adds {{orphaned fairuse replaced}} with today's date automatically filled in (takes the name of the replacement image as parameter).
- {{prod}} — Proposed deletion, adds {{dated prod}} with today's date automatically filled in.
- {{rfu}} — For fair use images that it should be possible to replace with a free licensed image, adds {{replaceable fair use}}, with today's date automatically filled in.
- {{refu-c}} — Used in captions of images flagged as replaceable fair use, adds {{rfu-c}} with the "due date" (today + 7 days) automatically calculated and filled in.
Templates that should not be substituted
Technically, templates shall not be substituted that
- (a) contain calls to ParserFunctions (#if, #switch, etc.) and
- (b) template calls that do leave some parameters to their defaults by not specifying them
because those constructs are not replaced in the generated wiki-code (Substing of case (a) leaves the #if or #switch constructs verbatim at the subst location and (b) leaves constructs like "{{{1|default value}}}").
If specific consensus is to eliminate a particular call of such a template, Special:ExpandTemplates can be used to expand that call to plain wiki-syntax.
- (c) templates which contains external links as the formatting of the URL to perform queries or look-ups may change.
List
This is a list of templates that should not be substituted. This is because they can either contain formatting standard code, contain complex code, or contain code that breaks if substituted.
- {{!}} escapes a vertical bar for Wiki table syntax from the default parameter and ParserFunctions mechanisms.
- Various citation/reference templates (see WP:CITET) which contain very complex conditional code
- {{cleanup}}, {{wikify}}, {{merge}} and other cleanup templates — bots rely on them to sort into cleanup-by-month categories.
- {{copyvio}} — far too much wikicode, and a bot relies upon it to populate WP:CP with unlisted articles.
- {{dmoz}} {{yahoo}} — URL queries external web directories.
- {{fact}} - contains complex code.
- Various infoboxes - For sake of bot-identification and consistency
- {{Javadoc:SE}}, {{Javadoc:EE}} and {{Javadoc:SE-guide}} — conditional templates whose purpose is to update the links when the master template is updated.
- {{ISP}} {{AOL}} {{repeat vandal}} — not messages to the users (so it is no problem if they change from their original form), so no reason to subst, but the standard reasons not to subst apply.
- {{ln}} {{lnt}} etc., complex code.
- {{main}} maintains formatting standard.
- {{qif}}, {{switch}}, {{ifndef}} are also conditional templates; substituting breaks usage.
- {{See also}} — standard formatting for see also list.
- {{selfref}} - does not work when substed, as it is meant to contain different code in mirrors.
- {{Signpost-subscription}} (must be updated weekly).
- {{SharedIP}} {{SharedIPEDU}} {{Openproxy}} — contains URLs that perform DNS and blacklist lookups on external sites.
- Various {{stub}} templates for simplified usage and removal.
- {{talkarchive}}, {{archive}}
- {{tl}} {{tlp}} {{ttl}} {{ti}} {{tic}} {{tls}} {{cl}} {{ccl}}: Many very widely used ({{tl}} with over 70,000 transclusions at last count). Quicker to type than their substitutions, and non-substing them allows new Wikipedians will learn about them and be able to use them.
Wrong title templates
These templates -- used in the main-space -- add a comment about why an article is misnamed. The categories for these templates are being removed because they create a self-reference. Once the categories are removed, the "What links here" tool can be used to find all transclusions of the template. They should not be subst'd, because it will remove this method of finding where it is used.
- {{lowercase}}
- {{underscore}}
- {{lowercase and underscore}}
- {{longtitle}}
- {{pipe in title}}
- {{namespace}}
- {{bracketed}}
- {{pound}}
- {{no unicode character}}
- {{downsize}}
- {{wrongtitle}}
Chemical abbreviations
See Category:Chemical element symbol templates. These are used to simplify the entry of chemical formulae.
- {{Actinium}}, {{Aluminium}}, {{Americium}}, {{Antimony}}, {{Argon}}, {{Arsenic}}, {{Astatine}}
- {{Barium}}, {{Berkelium}}, {{Beryllium}}, {{Bismuth}}, {{Bohrium}}, {{Boron}}, {{Bromine}}
- {{Cadmium}}, {{Caesium}}, {{Calcium}}, {{Californium}}, {{Carbon}}, {{Cerium}}, {{Chlorine}}, {{Chromium}}, {{Cobalt}}, {{Copper}}, {{Curium}}
- {{Darmstadtium}}, {{Dubnium}}, {{Dysprosium}}
- {{Einsteinium}}, {{Erbium}}, {{Europium}}
- {{Fermium}}, {{Fluorine}}, {{Francium}}
- {{Gadolinium}}, {{Gallium}}, {{Germanium}}, {{Gold}}
- {{Hafnium}}, {{Hassium}}, {{Helium}}, {{Holmium}}, {{Hydrogen}}
- {{Indium}}, {{Iodine}}, {{Iridium}}, {{Iron}}
- {{Lanthanum}}, {{Lawrencium}}, {{Lead}}, {{Lithium}}, {{Lutetium}}
- {{Magnesium}}, {{Manganese}}, {{Meitnerium}}, {{Mendelevium}}, {{Mercury}}, {{Molybdenum}}
- {{Neodymium}}, {{Neon}}, {{Neptunium}}, {{Niobium}}, {{Nitrogen}}, {{Nobelium}}
- {{Osmium}}, {{Oxygen}}
- {{Palladium}}, {{Phosphorus}}, {{Platinum}}, {{Plutonium}}, {{Polonium}}, {{Potassium}}, {{Praseodymium}}, {{Promethium}}, {{Protactinium}}
- {{Radium}}, {{Radon}}, {{Rhenium}}, {{Rhodium}}, {{Roentgenium}}, {{Rubidium}}, {{Ruthenium}}, {{Rutherfordium}}
- {{Samarium}}, {{Scandium}}, {{Seaborgium}}, {{Selenium}}, {{Silicon}}, {{Silver}}, {{Sodium}}, {{Strontium}}, {{Sulfur}}
- {{Tantalum}}, {{Technetium}}, {{Tellurium}}, {{Terbium}}, {{Thallium}}, {{Thorium}}, {{Thulium}}, {{Tin}}, {{Titanium}}, {{Tungsten}}
- {{Ununbium}}, {{Ununhexium}}, {{Ununoctium}}, {{Ununpentium}}, {{Ununquadium}}, {{Ununseptium}}, {{Ununtrium}}, {{Uranium}}
- {{Vanadium}}
- {{Xenon}}
- {{Ytterbium}}, {{Yttrium}}
- {{Zinc}}, {{Zirconium}}
Deletion-related
Most templates related to renaming or deleting pages are used temporarily, and thus do not need to be substituted (it just makes more work to delete them).
- {{tfd2}} {{tfdnotice}} {{catfd}}
- {{ifd}} {{ifd2}} {{idw}} {{idw-uo}} {{idw-pui}} {{idw-cp}}
- {{cfdnotice}}
- {{sfd-t}} {{sfd-r}} {{sfd-c}} {{sfr-t}} {{sfr-c}}
- {{rfd}}
- and all in Category:Speedy deletion templates
- {{editprotected}} not deletion related, but also temporary
Exceptions: The following templates must be substituted in order to work correctly:
In addition, those templates which document a finished deletion process ({{afd top}}, etc.) should be substituted.
Standardised appearance templates
These templates are intended to standardise the appearance of pages across a system of pages, and should not be substituted as doing so would make it prohibitively labour-intensive to edit them.
Under debate
- {{moved}}, {{moved-n}}, . There are not that many articles on requested moves at one time, so there is little benefit, and it is easier for the admin to remove afterwards if the template has not been substituted, especially when there is other stuff near the template, especially other substituted templates.
- {{col-begin}} {{col-2}} {{col-3}} {{col-4}} {{col-end}} — alleged by some to simplify usage.
- {{clear}}, {{clearleft}} {{clearright}}
- {{ed}} {{ed2}} {{ed right}} {{edit}} — simplify addition of edit link to templates
- Some have suggested that since user sig templates should be substed, {{unsigned}}, {{unsigned2}} should be substed for the same reasons. However, the latter are all protected and will change much more infrequently than most signature templates; also, they are significantly longer.
See also
- Substitution documentation on Meta
- User:Pathoschild/Template substitution list (bot-parseable lists, last updated 12 September 2006)
- {{subst}} (A talkpage template that reminds users to subst)
- Substitution bots using this page
- Other substitution bots