Template:Convert/doc

This subpage contains documentation, categories, or other content that is not part of the template.
To view the template page itself, see Template:Convert.

---

ATTENTION

• The Convert template MAY OR MAY NOT work depending on the chosen conversion. Only a subset of hundreds of sub-templates currently exist on Commons (cf. talk page). Check the Examples section below first for expected output before using the template.
• You can use {{Size}} for 2D conversions (such as paintings).
• You might be looking for the unrelated Convert to x templates

Purpose

To show measurement quantities as primary and converted secondary units, with optional abbreviation or slash, such as distance "32 metres (100 ft)" or temperature "18 °C (64 °F)" or "18 °C/64 °F" with optional U.S. spellings or hyphenation.

Cross-posted by request from the English Wikipedia.

Usage

{{convert|original_value|original_unit|conversion_unit|round_to|...}}

Note

Numbers must be entered in unformatted form (without commas). For negative numbers (i.e. temperatures or precision) use a hyphen as the minus sign for the input number. Values output by the template will be displayed formatted and with a true minus sign where appropriate. Optional parameters, in examples below, allow abbreviated units (abbr=on), or U.S. spellings (sp=us for "meter"), or slash separation (disp=slash), or hyphenation (adj=on), etc.

Examples

Input	Displays as
{{convert|5959|m|ft|0}}	5,959 metres (19,551 ft)
{{convert|3.21|kg|lb}}	3.21 kilograms (7.1 lb)
{{convert|3.21|kg|lb|0}}	3.21 kilograms (7 lb)
{{convert|0|kg|lb}}	0 kilograms (0 lb)
{{convert|6|ft|5|in|m}}	6 feet 5 inches (2.0 m)
{{convert|18|°C|°F|sigfig=2}}	18 °C (60 °F)
{{convert|1250|sqft|sqm|lk=on}}	Template:Convert/sqft
{{convert|20.5|sqkm|sqmi|1|lk=on|abbr=on}}	Template:Convert/sqkm
{{convert|641|acre|sqmi sqkm|3|lk=on|abbr=on}}	Template:Convert/LonAonDbSoffNa
{{convert|641|acre|sqmi sqkm|2|lk=on|abbr=on}}	Template:Convert/LonAonDbSoffNa because 640 acres equals one square mile; 641 acres rounded to two decimal places would equal 1.00 sq mi.

Tricks

In order to...
Use U.S. spelling	attach |sp=us
Make units wikilinked	attach |lk=on to link all units attach |lk=in to link only the input units attach |lk=out to link only the output units (The manual of style suggests that you only link the first instance).
Use the singular for grammar	attach |adj=on (e.g. "The 190-foot (58 m) bridge" as opposed to "feet"). Note that this also adds hyphenation (as specified by the manual of style).
Abbreviate all units	attach |abbr=on
Use a / instead of ( )	attach |disp=slash (or shorthand: |disp=/) (e.g. 190 foot/58 metre). Note that when using slashes all unit names either spelt out in full or abbreviated (where there exists an abbreviation).
Use in a table	attach |disp=table Note: For use in tables the template must start on a new line after a pipe. Only the number will be displayed unless you set |abbr=on, |lk=on, |lk=in or |lk=out. Example: here
Round to a specified number of significant figures	attach |sigfig={some non-negative integer}
Let Convert decide the unit to convert to	skip the convert to parameter (which would otherwise be third unnamed parameter) e.g. {{convert|100|mi|0}} gives 100 miles (161 km).

Rounding

Convert supports four types of rounding.

Rounding to a given precision

Specify the desired precision with the fourth unnamed parameter or third unnamed parameter in the case where the convert to parameter is skipped (see above). The conversion is rounded off to the nearest power of 1/10 this number. For instance, if the result is 8621 and the round number is '-2', the result will be 8600. If the result is '234.0283043' and the round number is '0', the result will be 234.

Rounding to a given number of significant figures

Specify the desired number of significant figures using |sigfig={some non-negative integer} as noted above.

Combine both of the above

If both the desired precision and the desired number of significant figures are specified, the conversion will be rounded to the least precise of these.

Default rounding

If neither the desired precision nor the desired number of significant figures are specified, the conversion will be rounded either to a comparable precision as the input value (the number of decimals remains the same if the conversion is a multiplication by a number between 0.2 and 2, is decreased by 1 if the factor is between 2 and 20, etc.) or to two significant figures whichever is the most precise. An exception to this is temperature wherein the conversion will be rounded either to a comparable precision as the input value or to a comparable precision to that which would give three significant figures when expressed in kelvin whichever is the most precise.

Units supported by {{Convert}}

The table below lists units supported by this template. It is divided up according to the quantity being measured. Not all supported units are listed here, there are links to complete lists for each quantity.

The codes listed in the code column (column 3) are accepted as input by the template. These can be used as the second or third unnamed parameter. For some units there exist alternative codes. These are listed in brackets and have been incorporated to make the code more flexible for editors, e.g. °F or F may be entered.

The codes listed in the combinations column (column 7) can be used to produce multiple conversions. They can only be used as the third unnamed parameter, e.g. {{convert|55|nmi|km mi}} produces 55 nautical miles (102 km; 63 mi).

Example/monitor page

Monitor quality or look at examples at Template:Convert/check

Implementation notes

Testing in December 2007 showed that Template:Convert can be used more than 300 times on one page to display converted measurements, so a small and uncomplicated template is of the essence. Accordingly, implementation had been changed from a large set of switch-statements to name-substitution invoking a few of over a thousand small sub-templates in the form "Convert/xxx_yyy" to branch by name depending on the conversion units and option in use.

Anomaly/error conditions

Because implementation is handled by selecting a few small subtemplates, very little is used of the overall template-processing resources (in the MediaWiki 1.6 language). In the rare event that template resources are exhausted, the message "Template:Convert" has appeared, repeated for each instance of the template:

Template:ConvertTemplate:ConvertTemplate:ConvertTemplate:Convert

Template:ConvertTemplate:ConvertTemplate:ConvertTemplate:Convert

However, the source of the problem is likely to be another, rather large, template used on the same page, which has exceeded template resources. With most large templates, even used several times on a page, the Convert template can still be used over 150 times per page.

Limited template resources

The issue of limited template-processing resources (although a very-huge limit) occurs in the MediaWiki 1.6 template/parser language: it might not be such a problem in some future release, probably beyond MediaWiki 1.8.2. The problem also involves the infamous noinclude-tag ("<noinclude>") which is implemented, internally, to actually do the exact opposite and include the skipped text within the template-processing buffers. The included noinclude text, such as "Category:" links and interwiki language links accumulates in the template buffers to allow error-traceback linked to that text. When a template is invoked 100 times, then 100 copies of that noinclude Category/interwiki text are stored in the processing buffers: the only reason it doesn't typically matter is that the template-processing buffers are absolutely, phenomenally huge (perhaps over 1.5 megabytes or 1536kb or over 24,000 lines of accumulated template text) for a single page.

The accumulation problem is related to the concept of a "memory leak" because each time a template is invoked, resources are eroded, and there is less buffer memory for processing the next template. Thinking of an article page as a template-expansion buffer is an analogy that illustrates the processing: rather than process templates serially, and accumulate only the results of expressions or if-statement logic, consider the page buffer as an expansion of all templates, all at once, until the entire page buffer is "de-templated" as a giant glob of inline text. In that analogy, all templates, as invoked, are duplicated umpteen times, repeating all if-statements and Category/interwiki links, over and over across the entire page buffer. There is a limit to that.

When space is critical, in a utility template used over 200 times, avoid Category-link and interwiki links, which should be moved to the "/doc" subfile, not included in the actual template as "noinclude" text: it is included during internal processing.

The hope for the future, from computer science, is that future versions of the MediaWiki language might process templates in serial fashion, deallocating intermediate space when a nested template is finished, and truly "nonincluding" the "<noinclude>" text as being totally omitted from the internal buffers. The current processing, however, is basically expanding each and every template (including noinclude-tag text) as a flat-text file into the template-processing buffers.

For those reasons, in MediaWiki 1.6, there is a limit to how many times template Convert can be invoked on one page, but the limit is over 300 times.