Module:Convert/doc: Difference between revisions

Revision as of 04:36, 11 December 2013

Latest revision as of 21:03, 31 July 2025

(44 intermediate revisions by 18 users not shown)

Line 1:

{{Transwiki guide|Template:Convert/Transwiki guide}}

{{High-risk}}

{{Module rating|p}}

{{cascade-protected template|page=module}}

{{Lua|Module:Convert/data|Module:Convert/text|Module:Convert/wikidata|Module:Convert/wikidata/data|Module:Convert/extra|Module:ConvertNumeric|noprotcat=yes}}

{{Uses TemplateStyles|Template:Fraction/styles.css|Template:Sfrac/styles.css|noprotcat=yes}}

This module converts a value from one unit of measurement to another. For example:

* <code><nowiki>{{convert|123|lb|kg}}</nowiki></code> → 123 pounds (56 kg)

The module is called using a template—parameters passed to the template are used by this module to control how a conversion is performed. For example, units can be abbreviated (like <code>kg</code>), or displayed as names (like <code>kilogram</code>), and the output value can be rounded to a specified precision. For usage information, see [[Help:Convert]].

The _convert() and _unit() functions can also be called from other Lua modules.

The template that invokes this module is:

*[[Template:Convert]]

== Templates and modules ==

The templateTemplates that invokesinvoke this module isare:

* {{t|convert}}

* {{t|cvt}} {{green|1=(convert with abbr=on)}}

The following modules are required:

* [[Module:Convert]] – ''(this module)'' code to convert units

* [[Module:Convert/data]] – unit definitions

* [[Module:Convert/text]] – text messages, and parameter names and values

The following modules are optional and are used only if required and if the module exists:

* [[Module:Convert/extra]] – extra (temporary) unit definitions; used if a unit is not found in [[Module:Convert/data]]

* [[Module:ConvertNumeric]] – code to spell an input value in words (only English is supported; however, see [[:vi:Module:ConvertNumeric]])

For Wikidata support the following modules are required:

* [[TemplateModule:Convert/wikidata]]

* [[Module:Convert/sandboxwikidata/data]]

The following help pages are available:

* [[Help:Convert]] – overview

* [[Help:Convert messages]] – describes error and warning messages; messages link to this page so it is required when the module is copied to another wiki

* [[Help:Convert units]] – overview of units

A page containing a convert error is added to one of the following categorieshidden category, providing the page is in a specified [[WP:Namespace|namespace]] (articles and templates, by default):

* {{clc|Convert errors}}

*[[:Category:Convert invalid units]]

*[[:Category:Convert invalid options]]

Units are defined in the wikitext of the master list of units.

* [[Module:Convert/documentation/conversion data/doc]] – master list of unit definitions

* [[Module:Convert/makeunits]] – translates wikitext from the master list to Lua

* [[Module talk:Convert/makeunits]] – makeunits results; copy the text to [[Module:Convert/data]]

[[Module:Convert/data]] is transcluded into every page using the convert module, so experimenting with a new unit in that module would involve a significant overhead. The [[Module:Convert/extra]] module is an alternative which is only transcluded on pages with a unit that is not defined in the main data module.

[[Module talk:Convert/show]] lists all unit links so they can be checked.

===Sandbox===

=== Sandbox= ==

When making a change, copy the current modules to the sandbox pages, then edit the sandbox copies:

{{#invoke:convert/tester|compare}}

*[[Module:Convert/sandbox]]

*[[Module:Convert/data/sandbox]]

*[[Module:Convert/text/sandbox]]

*[[Module:Convert/extra/sandbox]]

Use the following template to test the results (example <code><nowiki>{{convert/sandbox|123|lb|kg}}</nowiki></code>):

* [[Template:Convert/sandbox]]

[[Template:Convert/sandbox]] invokes [[Module:Convert/sandbox]] with parameter {{para|sandbox|onsandbox}} which causes convert to use the sandbox modules rather than the normal modules.

The following should be used to test the results of editing the convert modules.

* [[Template:Convert/testcases#Sandbox testcases]] – links to testcases

*[[Module:Convert/tester]] – module to run tests by comparing template output with fixed text

* [[Module:Convert/sandbox/testcasestester]] – templatesmodule to berun tested,tests withby expectedcomparing outputstemplate (usesoutput thewith testerfixed module)text

*[[Module talk:Convert/sandbox/testcases]] – view test results

It is not necessary to save thea testcases page before viewing test results. For example, [[ModuleTemplate:Convert/sandbox/testcases/sandbox4]] could be edited to change the tests. While still editing that page, paste {{nowrap|"<code>ModuleTemplate talk:Convert/sandbox/testcases/sandbox4</code>"}} (without quotes) into the page title box under "Preview page with this template", then click "Show preview".

=== Configuration= ==

The template that invokes this module can define options to configure the module. For example, to set the [[decimal mark]] to be a comma and the thousands separator to be a dot, use one of the following:

* <code><nowikisource lang='wikitext' inline>{{#invoke:convert | convert | numdot = , | numsep = . }}</nowiki></codesource>

* <source lang='lua' inline>p._convert({numdot=',', numsep='.'}, args)</source>

:Sets the [[decimal mark]] to be a comma, and the thousands separator to be a dot.

Other options, with default values, are:

* <code>|maxsigfig = 14</code> – maximum number of significant figures

* <code>|nscat = 0,10</code> – [[WP:Namespace|namespaces]] (comma separated) in which an error or warning adds a category to the page

* <code>|warnings = 0</code> – 0 (zero) disables warnings; 1 shows important warnings; 2 shows all warnings

*<code>sandbox = off</code> – on if the sandbox modules should be used

An option in the template can specify that the sandbox versions of the modules be used. If specified, the text on the right-hand side of the equals sign must be the name of the subpage for each sandbox module.

* <code>|sandbox=sandbox</code> – omit for normal operation

All text used for input parameters and for output messages and categories can be customized. For example, at enwiki the option <code>|lk=on</code> can be used to link each displayed unit to its article. The "<code>lk</code>" and "<code>on</code>" can be replaced with any desired text. In addition, input and output numbers can be formatted and can use digits in the local language. See the [[Template:Convert/Transwiki guide/translate|translation guide]] for more information.

== To do ==

Other configuration is available in the <code>translation_table</code> at [[Module:Convert/text]]. For example, [[:bn:Module:Convert/text]] uses:

Document the modules to access Wikidata!

*<code>group = 2</code> – group numbers 3 digits, then 2 digits

*<code>plural_suffix = <nowiki>''</nowiki></code> – disable plural unit names (do not append "s")

*Tables to translate digits to and from the English digits used in calculations.

== Module version history ==

[[Module:Convert/text]] contains all text used for input parameters and for output messages and categories. For example, <code>lk=on</code> may be used at en.wikipedia to link each displayed unit to its article. The text module could be edited to replace "<code>lk</code>" and "<code>on</code>" with any desired text.

* [[Template talk:Convert/Archive December 2013#Request to switch to Module:Convert|Version 1]] December 2013

* [[Template talk:Convert/Archive January 2014#Module v2 soon|Version 2]] January 2014

* [[Template talk:Convert/Archive April 2014#Module version 3|Version 3]] April 2014

* [[Template talk:Convert/Archive July 2014#Module version 4|Version 4]] July 2014

* [[Template talk:Convert/Archive September 2014#Module version 5|Version 5]] September 2014

* [[Template talk:Convert/Archive November 2014#Module version 6|Version 6]] November 2014

* [[Template talk:Convert/Archive December 2014#Module version 7|Version 7]] December 2014

* [[Template talk:Convert/Archive February 2015#Module version 8|Version 8]] February 2015

* [[Template talk:Convert/Archive February 2015#Module version 9|Version 9]] February 2015

* [[Template talk:Convert/Archive May 2015#Module version 10|Version 10]] May 2015

* [[Template talk:Convert/Archive June 2015#Module version 11|Version 11]] June 2015

* [[Template talk:Convert/Archive August 2015#Module version 12|Version 12]] August 2015

* [[Template talk:Convert/Archive March 2016#Module version 13|Version 13]] March 2016

* [[Template talk:Convert/Archive June 2016#Module version 14|Version 14]] June 2016 {{green|(introduced handling of Wikidata)}}

* [[Template talk:Convert/Archive September 2016#Module version 15|Version 15]] September 2016

* [[Template talk:Convert/Archive January 2017#Module version 16|Version 16]] January 2017

* [[Template talk:Convert/Archive May 2017#Module version 17|Version 17]] May 2017

* [[Template talk:Convert/Archive July 2017#Module version 18|Version 18]] July 2017

* [[Template talk:Convert/Archive August 2017#Module version 19|Version 19]] August 2017

* [[Template talk:Convert/Archive December 2017#Module version 20|Version 20]] December 2017 {{green|(changed symbols for dot and micro)}}

* [[Template talk:Convert/Archive January 2018#Module version 21|Version 21]] January 2018 {{green|(remove many deprecated options)}}

* [[Template talk:Convert/Archive February 2018#Module version 22|Version 22]] February 2018 {{green|(many unit link changes)}}

* [[Template talk:Convert/Archive June 2018#Module version 23|Version 23]] June 2018 {{green|1=(warnings for ignored numbered parameters; adj=pre/disp=preunit changes; currency units removed)}}

* [[Template talk:Convert/Archive May 2019#Module version 24|Version 24]] May 2019 {{green|1=(hidden sort key uses data-sort-value; avoid using the extra data module)}}

* [[Template talk:Convert/Archive 2#Module version 25|Version 25]] May 2021 {{green|1=(use templatestyles [[Template:Fraction/styles.css]] or [[Template:Sfrac/styles.css]] for fractions)}}

* [[Template talk:Convert/Archive 2#Module version 26|Version 26]] June 2021 {{green|1=(many unit link changes)}}

* [[Template talk:Convert/Archive 2#Module version 27|Version 27]] February 2022 {{green|1=(enhance Mach parameters; use spaced en dash when needed; unit tweaks)}}

* [[Template talk:Convert/Archive 3#Module version 28|Version 28]] April 2023 {{green|1=(new SI prefixes; add disp=semicolon; unit adjustments including fixing scales of mpge and BTU/lb)}}

* [[Template talk:Convert/Archive 3#Module version 29|Version 29]] May 2023 {{green|1=(liter/litre fix to show symbol 'L' rather than 'l' per MOS)}}

* [[Template talk:Convert/Archive 3#Module version 30|Version 30]] October 2024 {{green|1=(units can use convertPlural in languages with more than one plural form and can have a pername; E3km displays "thousand" even with abbr=on)}}

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox||

[[Category:Modules that add a tracking category]]

}}</includeonly>

<noinclude>

[[Category:Module documentation pages]]

</noinclude>