Extension:UnitsFormatter

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.svg
UnitsFormatter

Release status:Extension status experimental

ImplementationTemplate:Extension#type Tag
DescriptionTemplate:Extension#description This extension enables intelligent and flexible formatting of units of measure.
Author(s)Template:Extension#username Johan the Ghost
Latest versionTemplate:Extension#version 0.1
MediaWikiTemplate:Extension#mediawiki 1.9
LicenseTemplate:Extension#license No license specified
Download Version 0.1

Translate the UnitsFormatter extension if it is available at translatewiki.net

Check usage and version matrix.

What can this extension do?[edit]

This extension:

  • allows article authors to use a simple markup to enter quantities. Quantities can be entered in a single unit; authors don't need to worry about conversions.
  • allows users to select what style of units these quantities are displayed in. Users can select between metric and non-metric units, or both; for non-metric, they can select between British and US units.

For example, this text talks about fuel consumption, with units formatted as per Wikipedia standards:

My car burns 7.2 [[wikipedia:gallon|U.S. gallons]]

(27.3 [[wikipedia:litre|l]]) of gas every
100 [[wikipedia:kilometre|kilometres]]

(62 [[wikipedia:mile|mi]]).

This rather fiddly markup produces (unconditionally):

My car burns 7.2 U.S. gallons (27.3 l) of gas every 100 kilometres (62 mi).

Using the UnitsFormatter extension, we can use this simpler input, which doesn't require the author to do any conversions:

My car burns <unit>7.2 usgal</unit> of gas every <unit>100 km!</unit>.

(The "!" after "km" in this example fixes km as the primary unit for the distance.) This markup can produce any of the following outputs, or others, depending on user preferences:

My car burns 7.2 US gallons (27.3 l) of gas every 100 kilometres (62 mi).
My car burns 6.0 British gallons of gas every 100 kilometres.
My car burns 27.3 litres (6.0 Br gal) of gas every 100 kilometres (62 mi).

All the required markup, including non-breaking spaces and wikilinks, is generated. Furthermore, the displayed unit names and definition links are configurable in the MediaWiki: namespace. So for US-centric wikis, without changing all of the articles which use these units, the above can become:

My car burns 7.2 gallons (27.3 l) of gas every 100 kilometres (62 mi).

What it can't do[edit]

What it can't do[edit]

This is not a unit converter. If that's what you want, do it some other way. For example, this apparently obvious markup:

<unit>1.0 usgal</unit> equals <unit>3.785412 l</unit>

will, depending on user preferences, produce something like:

0.8 British gallons equals 0.832674 British gallons

Here, the user has elected to see units in British units, so both the inputs are converted to British gallons. The values are different because the inputs had different numbers of decimals. Not very useful! Just drop the <unit> tags, and simply write:

1 US gallon equals 3.785412 litres

Usage[edit]

Wiki users[edit]

The wiki users select the style of units they prefer to see in the "preferences" screen. Each <unit> tag in any article is then formatted for that user according to his/her preferences.

Currently, the GUI for user configuration is very crude; this is because an extension can only add simple checkboxes to the user's preferences screens. In future, this could be improved with a preferences tab dedicated to units.

The following checkboxes are added to the "Misc" preferences tab:

Prefer the article's units
if checked, the units stated in the article are used as the primary units.
Prefer metric units
if checked, the primary units are metric; otherwise, non-metric.
For non-metric, prefer British over US units
if checked, uses British instead of U.S. gallons, etc.
Show both metric and non-metric units
if checked, shows dual units; like "3 meters (10 ft)".

Article authors[edit]

For article authors, it's just a case of using the <unit> tag to represent units. This tag has the following syntax:

<unit [ digits = n realm = realm alt = unit ] > value unit </unit>

The parameters are:

value
the numerical value of the quantity to be displayed. Must be in decimal notation, eg. 0.00123.
unit
the ID of the unit; eg. km, mi. Must be one of the unit identifiers listed in the units table. Appending a "!" character to the unit name causes that unit to be used as the primary unit in the output regardless of user preferences; if the user has selected dual units, they will still be displayed.
digits
(optional) The number of decimal digits to display; defaults to the number of decimals in value. The number of digits is interpreted with regard to the units supplied as input, and is additionally scaled appropriately for the conversion in force; see "Rounding and scaling" below.
realm
(optional) The preferred realm for this conversion; this is a hint that, for example, we are talking about nautical as opposed to land measurements. See "Realms" below.
alt
(optional) An alternate unit to display as well as the user-selected units. For example, specify k to ensure that a temperature is displayed in Kelvin as well as Celcius and/or Fahrenheit.

Examples:

Input Possible outputs What it does
<unit>3 m</unit> 3 meters (10 ft)

10 feet (3 m)

Displays a length of 3 metres in the user's preferred units, with no decimal places.
<unit digits=3>4 brgal</unit> 18.184 litres (4.804 US gal)

4.804 US gallons

Displays a volume of 4 British gallons in the user's preferred units (in this case using US and metric units), with 3 decimal places.
<unit alt="k">-40 c</unit> -40 °C (-40 °F, 233 K)

-40 °F (233 K)

Displays a temperature of -40 °C in the user's preferred units and in Kelvin.
<unit>4.0 ft!</unit> 4.0 feet (1.2 m)

4.0 feet

Displays a length of 4.0 feet in feet, and in metric if selected by the user's preferences.

Article authors can, of course, state measures in any supported units. However, it is recommended that the most natural units for the subject be used — for example, an article about U.S. vehicle standards should use U.S. gallons. Thus, users who use the "prefer the article's units" mode will see units relevant to the subject first, followed by other units which that user has selected.

Rounding and scaling[edit]

Sometimes a unit conversion has the potential to result in loss of information due to mismatched unit magnitudes. For example, <unit>3 mm</unit>, if converted with no regard for precision, would produce the output "0 inches (3 mm)" — with no decimal places, the result in inches is zero.

To avoid this, we calculate the order-of-magnitude change involved in a conversion, and adjust the number of decimals upwards or downwards accordingly; likewise, we round digits before the point if appropriate. So, for example:

  • 3mm converts to 0.1 inches, not 0 inches (avoiding loss of precision)
  • 1.000 acre converts to 4,046.9 m² (if you force conversion to m²), not 4,046.856 m² (avoiding spurious precision).
  • 1.000 square mile converts to 2,590,000 m², not 2,589,988 m² (avoiding spurious precision).

The digits parameter to the <unit> tag is interpreted with respect to the input units, and is adjusted for converted units. Hence, <unit digits=2>4 ft</unit> will display in metric as "1.219 m".

Article authors must ensure that the results are useful in all units; hence, it is strongly recommended that authors set the "Show both metric and non-metric units" user preference (see above).

Realms[edit]

Some units are associated with particular realms of interest. For example, miles per hour and knots are both roughly equivalent non-metric units of speed; but knots are the ones most commonly used in nautical topics.

Certain units are tagged with their realm of interest, as shown in the units table. Currently, we have the following realms:

naut
subject is nautical; use customary nautical units where appropriate.
oil
the measure relates to quantities of oil (as in crude oil trading); use oil units where appropriate.

An article author can specify the realm of interest using the realm parameter; if units with the indicated realm exist, they will take precedence. If no realm is specified, and the input units have an associated realm, that realm will be used — this makes life even easier if the input units are already the preferred ones for the subject. Note that this only selects between units of a given locale; none of this overrides the user's preferences of which locale to display.

Some examples will clarify this. For these examples, the user's preferences have selected metric as the primary units, and non-metric as secondary:

Input Possible output What it does
<unit>12 km/h</unit> 12 kilometres per hour (7 mph) Display a speed of 12 km/h, in the default realm.
<unit realm=naut>12 km/h</unit> 12 kilometres per hour (6 kt) Display a speed of 12 km/h, in the naut realm. This causes knots to be preferred over mph for non-metric units.
<unit>9.1 kt</unit> 16.9 kilometres per hour (9.1 kt) Display a speed of 9.1 knots, which implicitly selects the naut realm.

Time[edit]

Some units, such as for time, don't have metric/Imperial alternatives; the unit of time is a second in all systems. (A minute is an alternative measure of time, but not in terms of metric v. Imperial.) Hence, <unit>5.00 s</unit> simply displays as "5.00 seconds". The only benefit of using <unit> here is that it will generate the right markup, in terms of inserting a non-breaking space, and making the wikilink to the unit definition the first time it is used.

Units[edit]

A table of known units can be produced with the <showunits /> tag, which is just used thus:

<showunits />

This displays the configuration data, including Wiki messages, for all units.

The table of units currently supported can be viewed at Extension:UnitsFormatter/Unit table.

Installation[edit]

  1. Download the extension code:
  2. Save the code in your wiki's extensions directory as extensions/UnitsFormatter.php.

Changes to LocalSettings.php[edit]

require_once("$IP/extensions/UnitsFormatter.php");

Configuration[edit]

Wiki Messages[edit]

The following wiki system messages are used. These are given default values, but can be overridden by editing Mediawiki:message.

These messages configure the preferences GUI:

tog-preferinput
the label for the 'Prefer the article's units' preferences checkbox.
tog-prefermetric
the label for the 'Prefer metric units' preferences checkbox.
tog-preferbritish
the label for the 'Prefer British over US units' preferences checkbox.
tog-dualunits
the label for the 'Show both metric and non-metric' preferences checkbox.

This message changes the working of links to unit definition articles:

unit-link-prefix
the interwiki prefix which is prepended to all links. This can be left blank, in which case the link "metre", for example, will attempt to link to the article [[metre]]. Most wikis will set this to their interwiki link to get to Wikipedia, eg. "wikipedia:", in which case the link for "metre" becomes [[wikipedia:metre]].

Unit Messages[edit]

The names and abbreviations displayed for units are configured using wiki system messages. Each unit U has four messages associated with it:

unit-U-name
the singular name of the unit.
unit-U-names
the plural name of the unit.
unit-U-ab
the abbreviation for the unit.
unit-U-link
a wikilink to a page providing a definition of the unit.

These messages can be configured to taste, by navigating to Mediawiki:message. For example, for the unit "ft", we have:

Message Default
unit-ft-name foot
unit-ft-names feet
unit-ft-ab ft
unit-ft-link foot (unit of length)

The link is just the Wiki page name. The content of the system message 'unit-link-prefix' (see above) will be prepended to this; eg. "w:".

Unit Data[edit]

The units themselves are configured in the code, in the $conversions table; the unit names are set up in the $unitMsgList table. Take care to keep both tables in step. The comments in the code explain the formats of the tables.

Other languages[edit]

I (JohanTheGhost) apologise for making this extension available only in English. However, adding other languages should be pretty easy.

  • The $unitMsgList table sets up the unit names, abbreviations, and wikilinks; it has one sub-table per language, so just add new sub-tables for new languages.
  • The $messageList table sets up other messages used by the extension; again, just add new sub-tables for new languages.

Outstanding Issues[edit]

Compound units[edit]

Compound units (eg. metres/second) are currently configured as individual fixed units -- ie. there is no support for combining units in a general way. This has been prototyped to some extent, but it gets very complex, and we end up with huge amounts of code to just format units.

Also, it raises new problems of unit equivalence. For example, metres naturally convert to yards; but metres/second should convert to feet/second, which is by far the more common non-metric measure of speeds. There's really no way that a generalised compound unit algorithm could know this, unless rules are programmed for specific unit combinations; and if we're going to do that, we may as well just program the compound units as simple units, which is what we've done.

Another problem would be with unit names. A nautical speed would need to be entered as 'nm/hr', in order to convert to 'km/hr'; this would display as 'nm/hr', or 'nautical mile per hour', where 'kt' or 'knot' is far more appropriate. Again, individual rules could be coded for this, but again we may as well just enter the compound units explicitly, as we have done.

Cacheing[edit]

This extension diminishes the effectiveness of the page cache. To allow different users to see pages with different presentations according to user preferences, pages are cached by name and by a hash of the user's preferences. This extension adds preferences, and hence will increase the number of different versions of each page in the cache, thus requiring more pages to be re-rendered from source.

The effect of this could be reduced by reducing the number of user options.

User preferences GUI[edit]

As mentioned above, the preferences GUI is very crude. A better GUI would use a dedicated "Units" tab with drop-down lists to select primary and secondary units, or something.

Right now there is no hook to allow this kind of GUI; so, for now, we stick with the simple checkboxes. If this extension becomes more mainstream, a better GUI should be devised, probably supported by a new hook in the preferences screen.