Module:Convert/documentation/conversion data/introduction: Difference between revisions

Content deleted Content added

Inline

Revision as of 09:40, 20 June 2013

Following is the master list of conversion data used by Module:Convert (under development—overview).

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

Table format

Format

The script that reads this page ignores everything except for the wikitext in the following sections:

== Conversions ==

== Input multiples ==

== Output multiples ==

== Combinations ==

== Defaults ==

== Links ==

== Overrides ==

In those sections, a level-3 heading (like === Length ===) starts a table that defines units of a certain type. In the subsection, lines that start with | are processed (all other lines, and lines that start with |- or |}, are ignored). A processed line is split into fields (delimited with ||), 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 colspan="11" | before the text to avoid it wrapping in a narrow column. Any such colspan 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 ft2 is an alias for sqft, and that is indicated by entering =sqft in the Symbol column for the ft2 entry. An alias can only be entered after the primary unit has been defined (the sqft entry must precede the ft2 entry). Normally there are no other entries on an alias line, however, the following may be used:

sp=us to specify that using the alias forces US spelling for that unit
default = unit code to specify that the alias has a default output that is different from the primary unit
link = link text to specify that the alias has a link that is different from the primary unit
symbol = symbol text to specify that the alias has a symbol that is different from the primary unit

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 feet should not be used, and that is indicated by entering !Message in the Symbol column for the feet entry. There should be no other entries on an error line. The Message text is displayed as an error if feet is used in a conversion. The text should use the special codes %{ and %} on each side of a unit code. Those codes are replaced with wikitext defined in Module:Convert, and which applies a consistent style.

Use name

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

SI prefixes

The prefix column should be empty if SI prefixes are not used, or should be SI for a normal unit that accepts SI prefixes. Unit m2 should have prefix SI2 so that, for example, km2 will be regarded as 1000 × 1000 of the m2 base unit. Similarly, unit m3 should have prefix SI3.

Name

Any %s 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 %s if the unit accepts prefixes, and if the prefix is not at the start of the unit's name.

Exceptions

Spelling exceptions can be handled by entering a row with the exception (for example, see ha which sets the unit name to "hectare"; without that row, the a row would cause ha to have the name "hectoare").

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.

Extra

The Extra column is usually empty, but can contain a value or code when more than a simple Scale is required for a conversion. There are two codes used with fuel efficiency units: volume/length and length/volume. 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 Mach 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.

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 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 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, v represents the input value specified in the convert template, and exclamation marks (!) 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 in (inch):

v < 36 ! mm ! cm

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 mm; otherwise, it is cm.

If present, the fourth field is appended to the result. For example, the following expression might be used for unit Ml (megalitre):

v < 28.316846592 ! e3 ! e6 ! cuft

If the condition is true, the result is e3cuft; otherwise, it is e6cuft.

Composite

A composite input unit consists of two standard units, where the second is a subdivision of the first. For example, |2|ft|6|in may be used to specify 2 feet 6 inches as the input unit in a conversion. See the Input multiples section.

Multiple

A multiple is a unit code that can be used as an output. For example, ftin is a multiple that results in a length being expressed in feet and inches. Each multiple may have up to four components which are defined in the Output multiples section.

Link

The link column is the title of the article related to that unit. If the link is preceded with + or *, 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 +[[Gallon]], then if the symbol is linked, it would appear as "US gal" ("US" and "gal" are linked to two different articles). If the link is *[[Gallon]], it would appear as "U.S. gal".

Similarly, if the link is preceded with @, 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 @[[Gallon]], then if the symbol is linked, it would appear as "imp gal".

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

Override

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

Known problems

Some infrequently used units have not yet been implemented, and there are some minor differences in the output produced by the module, when compared with the existing templates (see the testcases).

Engineering notation

In addition to the units defined in the data below, large scale units such as e6km (million kilometres) may be used. The following prefixes may be used, and the linked names are shown if lk is on:

e3 (thousand)
e6 (million)
e9 (billion)
e12 (trillion)
e15 (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.

@@ Line 2: / Line 2: @@
 </noinclude>Following is the master list of conversion data used by [[Module:Convert]] (under development—[[Module talk:Convert#Overview|overview]]).
-This page is read by a script (available [[User:Johnuniq/Making the units table|here]]). 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]].
+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]].
 == Table format ==
+=== Format ===
-'''Format''' The script that reads this page ignores everything except for the wikitext in the following sections:
+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>
@@ Line 18: / Line 19: @@
 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 ===
-'''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:
+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>sp=us</code> to specify that using the alias forces US spelling for that unit
 *<code>default = ''unit code''</code> to specify that the alias has a default output that is different from the primary unit
@@ Line 24: / Line 26: @@
 *<code>symbol = ''symbol text''</code> to specify that the alias has a symbol that is different from the primary unit
+=== Should be ===
-'''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 codes <code>%{</code> and <code>%}</code> on each side of a unit code. Those codes are replaced with wikitext defined in [[Module:Convert]], and which applies a consistent style.
+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 codes <code>%{</code> and <code>%}</code> on each side of a unit code. Those codes are replaced with wikitext defined in [[Module:Convert]], and which applies a consistent style.
+=== Use name ===
-'''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.
+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.
+=== SI prefixes ===
-'''SI prefixes''' The prefix column should be empty if SI prefixes are not used, or should be <code>SI</code> for a normal unit that accepts SI prefixes. Unit <code>m2</code> should have prefix <code>SI2</code> so that, for example, <code>km2</code> will be regarded as 1000&nbsp;×&nbsp;1000 of the <code>m2</code> base unit. Similarly, unit <code>m3</code> should have prefix <code>SI3</code>.
+The prefix column should be empty if SI prefixes are not used, or should be <code>SI</code> for a normal unit that accepts SI prefixes. Unit <code>m2</code> should have prefix <code>SI2</code> so that, for example, <code>km2</code> will be regarded as 1000&nbsp;×&nbsp;1000 of the <code>m2</code> base unit. Similarly, unit <code>m3</code> should have prefix <code>SI3</code>.
+=== Name ===
-'''Name''' 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.
+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.
+=== Exceptions ===
-'''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").
+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").
+=== Scale ===
-'''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.
+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.
+=== Extra ===
-'''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 script. Any other text is used as an offset in the conversion calculation that occurs with temperature units.
+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 ===
-'''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 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.
+=== Default ===
-'''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 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):
@@ Line 50: / Line 61: @@
 If the condition is true, the result is <code>e3cuft</code>; otherwise, it is <code>e6cuft</code>.
+=== Composite ===
-'''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.
+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.
+=== Multiple ===
-'''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. Each multiple may have up to four components which are defined in the [[#Output multiples|Output multiples]] section.
+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. Each multiple may have up to four components which are defined in the [[#Output multiples|Output multiples]] section.
+=== Link ===
-'''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]]". If the link is <code><nowiki>*[[Gallon]]</nowiki></code>, it would appear as "[[United States customary units|U.S.]] [[Gallon|gal]]".
+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" are linked 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]]".
@@ Line 62: / Line 76: @@
 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 ===
-'''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.
+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.
 == Known problems ==
@@ Line 68: / Line 83: @@
 == 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:
+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 <code>lk</code> is on:
 * <code>e3</code> (thousand)
 * <code>e6</code> (million)
-* <code>e9</code> (billion)
+* <code>e9</code> ([[1000000000 (number)|billion]])
-* <code>e12</code> (trillion)
+* <code>e12</code> ([[1000000000000 (number)|trillion]])
-* <code>e15</code> (quadrillion)
+* <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.