Template:Convert/doc

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 for 2D conversions (such as paintings).

Purpose
To show measurement quantities as primary and converted secondary units, with optional abbreviation or slash, such as distance "32 m" or temperature "18 °C" or "18 °C" with optional U.S. spellings or hyphenation.

Cross-posted by request from the English Wikipedia.

Usage
 original_value original_unit 


 * 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.

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  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 undefined undefined
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.  produces 55 nmi.

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 ("&lt;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 "&lt;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.