View source for Module:Convert/documentation/conversion data/introduction

<noinclude>{{notice|1=This documentation is transcluded at the start of the [[Module:Convert/documentation/conversion data|conversion data page]].}}
</noinclude>{{ombox |small=yes |style=width:170px; |text=This documentation<br />is transcluded<br /><noinclude>[[Module:Convert/documentation/conversion data|there]]</noinclude><includeonly>from [[Module:Convert/documentation/conversion data/introduction|here]]</includeonly>.}}
Following is the master list of conversion data used by [[Module:Convert]], although more units may temporarily be at [[Module:Convert/extra]]. Units should be discussed at [[Template talk:Convert]].

This page is read by a script ([[Module:Convert/makeunits|makeunits]]). The script extracts information from the wikitext, and outputs the [[Lua (programming language)|Lua]] source that defines the table of units; that source can be manually copied into [[Module:Convert/data]].

==Conversion factors and physical constants==

The values for most of the conversion factors used by [[Template:Convert]] come from international and national standards documents:
* {{cite book |author=Organisation Intergouvernementale de la Convention du Mètre |title=The International System of Units (SI) |url=https://www.bipm.org/utils/common/pdf/si_brochure_8_en.pdf |publisher=[[Bureau International des Poids et Mesures]] |orig-year=2006 |year=2014 |accessdate=26 June 2018}} This documents links to the NIST document in section 4.2 "Other non-SI units not recommended for use".
* {{cite book |last1=Thompson |first1=Ambler |last2=Taylor |first2=Barry N. |title=Guide for the Use of the International System of Units (SI) - Publication 811, 2008 Edition, 2nd printing |date=November 2008 |url=https://nvlpubs.nist.gov/nistpubs/Legacy/SP/nistspecialpublication811e2008.pdf |publisher=[[National Institute of Standards and Technology]], U.S. Department of Commerce |accessdate=26 June 2018}}

The NIST document gives conversion factors correct to 7 places. Factors in bold are exact. If exact factors have more than 7 places, they are rounded and no longer exact. This convert module replaces these rounded figures with the exact figures. For example, the NIST document has 1 square mile = 2.589 988 E+06 square meters. The convert template has 1 square mile = 2,589,988.110336 square meters.

Values for the fundamental physical constants come from the ''NIST Reference on Constants, Units, and Uncertainty'', either the 2010 or the 2014 version. The 2018 version is in preparation. While the articles on the units should be updated as the new versions come out every four years, the few more [[significant figures]] provided are probably not necessary for the way this template is used. 
* {{cite web |title=CODATA 2010 Table at NIST |url=https://physics.nist.gov/cuu/pdf/all_2010.pdf}} From {{cite journal |last1=Mohr |first1=Peter J. |last2=Taylor |first2=Barry N. |last3=Newell |first3=David B. |title=CODATA recommended values of the fundamental physical constants: 2010 |journal=Reviews of Modern Physics|volume=84 |issue=4 |year=2012 |pages=1527–1605 |doi=10.1103/RevModPhys.84.1527}}
* {{cite web |title=CODATA 2014 Table at NIST |url=https://physics.nist.gov/cgi-bin/cuu/Category?view=pdf&All+values.x=57&All+values.y=9}} From {{cite journal |last1=Mohr |first1=Peter J. |last2=Newell |first2=David B. |last3=Taylor |first3=Barry N. |title=CODATA recommended values of the fundamental physical constants: 2014 |journal=Reviews of Modern Physics |volume=88 |issue=3 |year=2016 |doi=10.1103/RevModPhys.88.035009}}

Definitions for additional historical measures are found in sources such as
* {{cite book |last=Fenna |first=Donald |title=A Dictionary of Weights, Measures, and Units |year=2002 |publisher=Oxford University Press |isbn=978-0-19-107898-9}}

== Table format ==
=== Format ===
The script that reads this page ignores everything except for the wikitext in the following sections:
:: <code>{{nowrap|1=== Conversions ==}}</code>
:: <code>{{nowrap|1=== Input multiples ==}}</code>
:: <code>{{nowrap|1=== Output multiples ==}}</code>
:: <code>{{nowrap|1=== Combinations ==}}</code>
:: <code>{{nowrap|1=== Defaults ==}}</code>
:: <code>{{nowrap|1=== Links ==}}</code>
:: <code>{{nowrap|1=== Automatic per units ==}}</code>
:: <code>{{nowrap|1=== Overrides ==}}</code>
:: <code>{{nowrap|1=== Variable names ==}}</code> {{green|(used at [[:sl:Module:Convert/documentation/conversion data/dok#Variable names|slwiki]])}}

In those sections, a level-3 heading (like <code>{{nowrap|1==== Length ===}}</code>) starts a table that defines units of a certain type. In the subsection, lines that start with <code>|</code> are processed (all other lines, and lines that start with <code>|-</code> or <code>|}</code>, are ignored). A processed line is split into fields (delimited with <code>||</code>), and leading/trailing whitespace is removed from each field. Empty fields in the Conversions section are given a default value (for example, the plural of ''yard'' is formed by adding ''s'', and the US names are also ''yard'' and ''yards'').

The second field in each row of the Conversions section normally specifies a unit's symbol, but it can be used for other purposes described in the following. In some cases the text in the second field can be long, and it is convenient to insert <code>colspan="11"&nbsp;|</code> before the text to avoid it wrapping in a narrow column. Any such <code>colspan</code> at the start of the second field is ignored.

=== Alias ===
Some unit codes are an alias for another spelling of the unit code. For example, the code <code>ft2</code> is an alias for <code>sqft</code>, and that is indicated by entering <code>=sqft</code> in the Symbol column for the <code>ft2</code> entry. An alias can only be entered after the primary unit has been defined (the <code>sqft</code> entry must precede the <code>ft2</code> entry).

Normally there are no other entries on an alias line, however, the following may be used:
*<code>default = ''unit code''</code> to specify that the alias has a default output that is different from the primary unit
*<code>link = ''link text''</code> to specify that the alias has a link that is different from the primary unit
*<code>multiplier = ''number''</code> used as "multiplier = 100" with unit code <code>100km</code> to define a unit that is 100 times the size of a kilometre
*<code>sp=us</code> (or <code>sp = us</code>) to specify that using the alias forces US spelling for that unit
*<code>symbol = ''symbol text''</code> to specify that the alias has a symbol that is different from the primary unit
*<code>symlink = ''link text''</code> to specify that the alias has a different link when abbreviated ("symbol link")

=== Per units ===
A unit can be defined as a ratio of two other units. For example, <code>L/km</code> can be defined as "liters per kilometer" by entering <code>==L/km</code> as the symbol for the unit. A single "<code>=</code>" is used with an alias to specify that a unit code is an alternative name for another unit. By contrast, if "<code>==</code>" is used, the unit code is defined as the first unit "per" the second.

As well as a ratio of two units, a per unit can be of the form "currency per unit". The module recognizes "$" and "£" as currency symbols and shows them appropriately. For example, the input <code>|120|$/acre</code> would be displayed as "$120 per acre", or "$120/acre" if abbreviated.

The definition for a per unit can be followed by the same modifiers available for an alias.

=== Should be ===
Some unit codes should not be used—if such a code is used, the template displays an error message telling the editor what unit code should be entered. For example, the code <code>feet</code> should not be used, and that is indicated by entering <code>!''Message''</code> in the Symbol column for the <code>feet</code> entry. There should be no other entries on an error line. The ''Message'' text is displayed as an error if <code>feet</code> is used in a conversion. The text should use the special format codes <code>%{</code> and <code>%}</code> on each side of a unit code. The format codes are replaced with wikitext defined in [[Module:Convert]], and which applies a consistent style to each displayed unit code.

=== Use name ===
Some units generally use their name, rather than a symbol. That is indicated by inserting <code>~</code> before the symbol. For example, the code <code>acre</code> has symbol <code>~acre</code> which means results will use the singular name "acre", or the plural name "acres", depending on the value.

=== Use unit code for default ===
Some units have a symbol prefixed with <code>*</code>, for example, the symbol given for <code>pitch</code> is <code>*µm</code>. Normally, when units are looked up in the [[#Defaults|Defaults]] or [[#Links|Links]] exception tables, the symbol of the unit is used. However, pitch has a symbol that conflicts with micrometre. The <code>*</code> prefix means that the unit code for <code>pitch</code> is used to look up exceptions, not the symbol.

=== SI prefixes ===
The prefix column should be empty if SI prefixes are not used, <code>SI</code> for a unit that accepts SI prefixes, <code>SI2</code> for a unit code that indicates a base unit squared, and <code>SI3</code> for cubed. For example when defining unit code <code>m2</code> put <code>SI2</code> here, and for <code>m3</code> say <code>SI3</code>.  This will scale, for example, <code>km2</code> to 1000&nbsp;×&nbsp;1000 of the base unit, <code>m</code>, or scale <code>mm3</code> to 0.001&nbsp;×&nbsp;0.001&nbsp;×&nbsp;0.001 of the base unit <code>m</code>.

=== Name ===
The name of the unit is required. The plural name is optional. If no plural name is given, it is created by appending "s" to the singular name. For example, the <code>ft</code> unit has name "foot" and plural name "feet"—the plural name is necessary to avoid the plural of "foot" being "foots".

The US name is optional. If no US name is given, it is the same as the normal name. The US plural name is optional—if it is missing it is created by appending "s" to the US name. When using {{tl|convert}}, the option {{para|sp|us}} causes the US name to be displayed if a name is required for the convert.

Any <code>%s</code> in the name columns is replaced with the appropriate SI prefix, or is removed if SI prefixes are not appropriate (not suitable for the unit, or not used in the conversion). It is only necessary to use <code>%s</code> if the unit accepts prefixes, and if the prefix is not at the start of the unit's name, for example with <code>m2</code> and <code>m3</code>.

=== Exceptions ===
Spelling exceptions can be handled by entering a row with the exception. For example, see <code>ha</code> which sets the unit name to "hectare"; without that row, the <code>a</code> row would cause <code>ha</code> to have the name "hectoare". There must be an [[#Override|override]] to document that an exception is intended.

=== Scale ===
The scale is a value or expression that is used as a factor to convert a value to its corresponding base unit. Commas may be used as a thousand separator (e.g. <code>1,000,000</code>) or [[Scientific_notation#E_notation|e notation]] may be used (e.g. <code>1e6</code>). Fractions should be used when required for exactness (e.g. <code>1/12</code>).

=== Extra ===
The <code>Extra</code> column is usually empty, but can contain a value or code when more than a simple <code>Scale</code> is required for a conversion. There are two codes used with fuel efficiency units: <code>volume/length</code> and <code>length/volume</code>. In addition, certain codes are required to indicate that the conversion procedure for the unit is built-in to the module. Any other text is used as an offset in the conversion calculation that occurs with temperature units.

=== Built-in units ===
The conversion procedure for some units (for example, the <code>Mach</code> unit of speed) are built into [[Module:Convert]] as they are too complex to be specified in a table. That is indicated by entering a code (which must be the same as used in the module) in the Extra column.

The script that reads this page contains a small amount of built-in data that does not conveniently fit into the tables below (see <code>set_builtins</code> in [[Module:Convert/makeunits|makeunits]]).

=== Default ===
A default is a code for a unit or combination that identifies the output unit or units that will be used if none is specified in the convert template. The [[#Defaults|Defaults]] section defines exceptions for unit codes with an SI prefix, where the default output is different from that of the base unit. Also, units using [[#Engineering notation|engineering notation]] may appear in the defaults section to define a default output for the unit.

A default may specify a unit code or an expression that tests the input value, and which produces one of two different outputs depending on that value. In the expression, <code>v</code> represents the input value specified in the convert template, and exclamation marks (<code>!</code>) are used to separate the expression into either three or four fields. For example, the following expression might be used as the default for unit <code>in</code> (inch):
: <code>v < 36 ! mm ! cm</code>
The first field is a condition which evaluates to ''true'' or ''false''. In this example, if the input value is less than 36, the default output unit is <code>mm</code>; otherwise, it is <code>cm</code>.

If present, the fourth field is appended to the result. For example, the following expression might be used for unit <code>Ml</code> (megalitre):
: <code>v < 28.316846592 ! e3 ! e6 ! cuft</code>
If the condition is true, the result is <code>e3cuft</code>; otherwise, it is <code>e6cuft</code>.

=== Composite ===
A composite input unit consists of two standard units, where the second is a subdivision of the first. For example, <code>|2|ft|6|in</code> may be used to specify 2&nbsp;feet 6&nbsp;inches as the input unit in a conversion. See the [[#Input multiples|Input multiples]] section.

Composites are defined in pairs, but any number of pairs can be used to specify an input. For example, given that <code>ch</code> is defined as a subdivision of <code>mi</code>, and that <code>ft</code> is a subdivision of <code>ch</code>, an input length could be specified as <code>1|mi|2|ch|3|ft</code>. Also, with suitable pairs defined, an input length could be specified as <code>4|mi|3|yd|2|ft|1|in</code>. There is no limit to the number of permitted subunits.

=== Multiple ===
A multiple is a unit code that can be used as an output. For example, <code>ftin</code> is a multiple that results in a length being expressed in feet and inches. A multiple may have any number of components defined in the [[#Output multiples|Output multiples]] section, where each component is a subdivision of the preceding unit.

=== Link ===
The link column is the title of the article related to that unit. If the link is preceded with <code>+</code> or <code>*</code>, extra text will be inserted before the link, and the text shown by the link will be adjusted to omit a prefix of "US" or "U.S.", if present. For example, if a unit has the symbol "US gal" (or "U.S. gal"), and if the link is <code><nowiki>+[[Gallon]]</nowiki></code>, then if the symbol is linked, it would appear as "[[United States customary units|US]] [[Gallon|gal]]" ("US" and "gal" link to two different articles). If the link is <code><nowiki>*[[Gallon]]</nowiki></code>, it would appear as "[[United States customary units|U.S.]] [[Gallon|gal]]".

Similarly, if the link is preceded with <code>@</code>, extra text will be inserted before the link, and the text shown by the link will be adjusted to omit a prefix of "imp" or "imperial", if present. For example, if a unit has the symbol "imp gal", and if the link is <code><nowiki>@[[Gallon]]</nowiki></code>, then if the symbol is linked, it would appear as "[[Imperial unit|imp]] [[Gallon|gal]]" ("imp" and "gal" link  two different articles).

The [[#Links|Links]] section defines exceptions for unit codes with an SI prefix, where the linked article is different from that of the base unit.

Pipe characters (<code>|</code>) in a table need to be [[Character encodings in HTML|encoded]]. For example, "<code><nowiki>[[Gallon|gal]]</nowiki></code>" should be entered as "<code><nowiki>[[Gallon&amp;#124;gal]]</nowiki></code>". The script that reads this page replaces each <code>&amp;#124;</code> with <code>|</code>.

=== Override ===
Some unit codes match a unit with an SI prefix, and duplicate unit codes are not permitted. For example, <code>Pa</code> can be interpreted as "peta-are" which would prevent the <code>pascal</code> unit of pressure being defined after the <code>are</code> unit of area. However, listing <code>Pa</code> in the [[#Overrides|Overrides]] section means that the pascal unit can be defined, in which case peta-are will not be available.

=== Conventions ===
Some unit codes are not intended to be used in a template, but are needed to define exceptions. For example, the code <code>ft</code> has link [[Foot (unit)]], but unit <code>psi/ft</code> needs <code>ft</code> to be linked to [[Fracture gradient]]. To handle such cases, a unit code starting with "<code>-</code>" is used (<code>-ft-frac</code> for feet with a link to fracture gradient).

If needed, more dashes can be used to define additional exceptions (for example, see <code>-Scwt</code> and <code>--Scwt</code>, which are similar to <code>Scwt</code> but have different names).

== Engineering notation ==
In addition to the units defined in the data below, large scale units such as <code>e6km</code> (million kilometres) may be used. The following prefixes may be used, and the linked names are shown if {{para|lk|on}}:
* <code>e3</code> (thousand)
* <code>e6</code> (million)
* <code>e9</code> ([[1000000000 (number)|billion]])
* <code>e12</code> ([[1000000000000 (number)|trillion]])
* <code>e15</code> ([[1000000000000000 (number)|quadrillion]])

Any standard unit (not a combination, multiple, or built-in) may be used after an engineering notation prefix, including "temperature change" units, but not "temperature" units.

== Notes on units ==
=== Energy and torque ===
By convention, units written as force-distance (such as lbft or kgf.m) are torque, and those written as distance-force (such as ftlbf) are energy. See [[WP:MOSNUM#Unit names]] and the [[WT:Manual of Style/Dates and numbers/Archive 135#Foot-pounds and pound-feet|discussion]], and see [[Pound-foot (torque)]] and [[Foot-pound (energy)]].

However, some topics use traditional units that conflict with the above convention. To handle these, [[Module:Convert/makeunits]] includes a <code>specials</code> table that adds an "alttype" (alternate type) field to certain whitelisted units. The alttype field allows conversion between units of different type, provided each unit is whitelisted to allow the conversion.

As at December 2013, the following energy units have alttype = "torque" (the first line consists of different units, while the second line consists of aliases for units in the first line):
*ftlb, ftlb-f, ftlbf, inlb, inlb-f, inlbf, inoz-f, inozf
*ft.lbf, ft·lb-f, ft·lbf, in.lb-f, in.lbf, in.oz-f, in.ozf, in·lb-f, in·lbf, in·oz-f, in·ozf

The following torque units have alttype = "energy":
*Nm
*N.m, N·m

For example, the following conversion works despite the fact that Nm is torque and ftlbf is energy:
*<code><nowiki>{{convert|1|Nm|ftlbf}}</nowiki></code> → {{convert|1|Nm|ftlbf}}