User:Johnuniq/Convert documentation
This page provides preliminary documentation for conversions using Module:Convert.
Differences from templates
The standard convert template is documented at Template:Convert/doc. The module supports everything on that page with the following differences:
- The text "Numbers must be entered in unformatted form (without commas)" does not apply to the template or the module.
- Using
{{subst:convert|...}}works with the module. - The module checks unit types and displays an error message if a mismatch occurs.
- The module does not have a problem with template loops, and will allow pointless conversions like
{{convert|123|m|m}}. - Ranges and
disp=flipshould work with all units. - Scaled units like
e6USgalare not predefined. With some exceptions, all units accept prefixes e3, e6, e9, e12, e15. - The module does not accept
0to mean "use the default unit". For example, the output unit must be specified in a conversion like{{convert|9|ft|m|adj=mid|-long}}. - The "under construction" section does not apply—all the listed options work with all units.
- The functionality of
{{convert/3}}and{{convert/4}}is handled by the module, except that the module does not support arbitrary text to separate items in a range. Furthermore, the predefined separator words such as "by" and "to" behave in exactly the same manner as they do for standard converts, so a conversion like{{convert/3|2|x|4|x|6|m|ft}}would need to use the new*separator rather thanxto produce exactly the same output with the module.
Limitations
This is a preliminary, not comprehensive, list of features that may be expected, but which will not work.
Some options allow extra unnamed parameters to be entered. Such options require that the output unit is specified—it is not possible to say "use the default unit". For example:
{{convert/sandboxlua|9|ft|m|adj=mid|-long}}→ 9-foot-long (2.7 m){{convert/sandboxlua|9|ft|m|abbr=off|disp=preunit|linear }}→ 9 linear feet (2.7 linear metres){{convert/sandboxlua|9|ft|adj=mid|-long}}→ 9-foot ([convert: unknown unit]){{convert/sandboxlua|9|ft|abbr=off|disp=preunit|linear }}→ 9 feet ([convert: unknown unit])
Composite units cannot be used in a range:
{{convert/sandboxlua|2|ft|6|in|to|3|ft|9|in}}→ 2 feet 6 inches ([convert: unknown unit])*
If an expression is wanted, it has to use {{#expr:...}}:
{{convert|3*12|ft|mm}}→ 3×12 feet (910×3,660 mm){{convert/sandboxlua|3*12|ft|mm}}→ 3×12 feet (910×3,660 mm){{convert/sandboxlua|{{#expr:3*12}}|ft|mm}}→ 36 feet (11,000 mm)
Options
The following options are available.
| Option | Description |
|---|---|
| abbr=comma | No comma in input or output numbers. |
| abbr=in | Use symbol for LHS unit. |
| abbr=mos | In a range, repeat the input unit (no longer used). |
| abbr=none | Old equivalent for "abbr=off". |
| abbr=off | Use name for all units. |
| abbr=on | Use symbol for all units. |
| abbr=out | Use symbol for RHS unit (default). |
| abbr=values | Show only input and output numbers, not units. |
| abbr=~ | Show input unit symbol as well as name. |
| adj=1 | Unit name is singular when value is 1 or less, but not zero. |
| adj=flip | Reverse order of input/output. |
| adj=j | Join value and unit name using " " instead of a space. |
| adj=mid | Same as adj=on with user-specified text before input unit. |
| adj=nocomma | No comma in input or output numbers. |
| adj=off | Ignored (off is the default). |
| adj=on | Unit name is singular and hyphenated. |
| adj=pre | User-specified text before input unit. |
| adj=ri1 | Round input with precision 1. |
| adj=ri2 | Round input with precision 2. |
| adj=ri3 | Round input with precision 3. |
| disp=/ | Join input/output using "/". |
| disp=2 | Display only output value and symbol/name. |
| disp=5 | Round output value to nearest 5. |
| disp=b | Join input/output using "(...)". |
| disp=br | Join input/output using "<br/>". |
| disp=comma | Join input/output using ",". |
| disp=flip | Reverse order of input/output. |
| disp=flip5 | Same as disp=flip with disp=5. |
| disp=nocomma | No comma in input or output numbers. |
| disp=number | Display output value only. |
| disp=or | Join input/output using "or". |
| disp=out | Same as disp=2. |
| disp=output number only | Same as disp=number. |
| disp=output only | Same as disp=2. |
| disp=preunit | User-specified text before input and output units. |
| disp=s | Same as disp=/. |
| disp=slash | Same as disp=/. |
| disp=sqbr | Join input/output using "[...]". |
| disp=table | Output is suitable for a table cell with align="right". |
| disp=tablecen | Output is suitable for a table cell with align="center". |
| disp=u2 | Display output symbol/name (not input; not output value). |
| disp=unit | Display input symbol/name (not output; not input value). |
| disp=unit2 | Same as disp=u2. |
| disp=x | Join input/output using user-specified text. |
| near=5 | Same as disp=5. |
| order=flip | Same as disp=flip. |
| comma=5 | Only use comma grouping if 5 or more digits. |
| comma=gaps | Use gaps, not comma, to separate groups of digits. |
| comma=gaps5 | Use gaps, but only if 5 or more digits. |
| debug=yes | Make the normally hidden sort key visible. |
| lang=en | Output English digits, regardless of local language. |
| lk=in | Link LHS unit name or symbol. |
| lk=off | Ignored (off is the default). |
| lk=on | Link all unit names or symbols (but not twice for the same unit). |
| lk=out | Link RHS unit name or symbol. |
| sigfig=N | Round output value to N significant figures (N is a positive integer). |
| sortable=off | Ignored (off is the default). |
| sortable=on | Output numeric hidden sort field for use in a sortable table. |
| sp=us | Use U.S. spelling (like "meter" instead of default "metre"). |
| spell=in | Spell input value in words. |
| spell=In | Spell input value in words with first letter uppercase. |
The near=5 and order=flip options are experiments to produce a more logical alternative syntax with more comprehensible wikitext.
Examples of number grouping:
{{convert/sandboxlua|1234|m|ft}}→ 1,234 metres (4,049 ft){{convert/sandboxlua|1234|m|ft|comma=5}}→ 1234 metres (4049 ft){{convert/sandboxlua|12345|m|ft|comma=5}}→ 12,345 metres (40,502 ft){{convert/sandboxlua|1234|m|ft|comma=gaps}}→ 1234 metres (4049 ft){{convert/sandboxlua|1234|m|ft|comma=gaps5}}→ 1,234 metres (4,049 ft)*{{convert/sandboxlua|123,456,789|m|ft|comma=gaps5}}→ 123,456,789 metres (405,041,959 ft)*
Examples of spelling input values:
{{convert/sandboxlua|10|mi|km|spell=in}}→ ten miles (16 km){{convert/sandboxlua|10|mi|km|spell=In}}→ Ten miles (16 km){{convert/sandboxlua|1/3|mi|km|adj=on|spell=in}}→ one-third-mile (0.54 km)
Option lang=en may be useful at other Wikipedias. For example, from the Bengali Wikipedia:
{{convert|1234|m|ft}}→ ১,২৩৪ মিটার (৪,০৪৯ ফু){{convert|1234|m|ft|lang=en}}→ 1,234 মিটার (4,049 ফু)
Extra features
User-defined combinations
Simple units can be combined with "+" to specify a combination of output units. Only simple units such as ft can be used, not units like ftin for feet and inches.
{{convert/sandboxlua|12|km2|acre+dunam+tsubo+ha}}→ 12 square kilometres (3,000 acres; 12,000 dunams; 3,600,000 tsubo; 1,200 ha){{convert/sandboxlua|22|ST|MT+LT|abbr=off|lk=on}}→ 22 short tons (20 metric tons; 20 long tons){{convert/sandboxlua|12|km|mi+yd+ha}}→ 12 kilometres ([convert: unit mismatch])