Module:Val/units/doc

This is the documentation page for Module:Val/units

Val units are published at Template:Val/list, but here is where they are configured.

Just edit this page and preview with Template:Val/list.

The common reference for a unit on the wiki is the unit code, which equates to the markup and link of a unit.

Anyone can just add a unit here, and it will work for Val. The remainder of this page contains items in there order of importance.

You can enter any units in the "Unsorted units" section if you are not sure where else.
There is local builtin_units_long_scale for long scale units, and local builtin_units for the rest.

If the same unit code is defined twice on this page, the later one overrides the earlier one.
See Wikipedia:Manual of Style/Dates and numbers#Units of measurement A.K.A. MOS:NUM.
Entries here override Convert. Enter a unit code and a wikilink. Done.
Convert and Val share units so you may need to visit either Template talk:Val/units or Template talk:Convert to get answers or assistance.

You can alias Convert or Val units. But these are different things.

A "unit code alias" is when the same unit pagename and unit symbol are defined twice. Unit code aliases are an important step in defining unit codes with alternate capitalization or dimensional attributes.
A "unit alias" is when Val or Convert alias one the another. A unit of measurement is here denoted ALIAS to mean "they are defined there". Val defaults to Convert, but it's good to this explicit for certain Val units: the ones tempting to define here, but that you don't want defined here because, says ALIAS, they are already defined there.
If your unit code is not listed at {{Val/list}}, you can check for it at {{Val/unitsfromconvert}}, or at {{Convert#Units}}

Val and Convert share unit codes, but their units of measurement are different.

Most of the wiki's unit codes are managed by {{Convert}}. At Convert the procedure for defining a unit is much more involved than it is here, because there every unit defined must reference associated units, conversion factors, alternate spellings, and many other attributes. An entry at Convert is defined as a multi-line, multi-attribute Lua table with its attendant syntax, and inside a larger Lua script.
Some very few unit codes here, like C and F, mean something different there. Val caters to Coulombs and Farads, while Convert caters to Celsius and Fahrenheit. Convert and Val unit codes are mostly identical like degC and degF.
Val could need any unit, while not all units are needed in conversions, so Val needs all of Convert's units and some of its own.

Customization may be a worthwhile risk.

Although units used in articles have definite stylistic standards, there remains room for depending on Val for markup (but see WP:Accessibility about color, link, and text).
You may want to customize some Val unit codes that will automate some Val markup for special articles, the talk page, etc. See WP:HTML#formatting for possibilities.

Defining a unit

To define a unit you edit this page and preview it with Template:Val/list. Preview your changes or additions before saving. That is done at the bottom of the edit box where it says Show preview. The Page title: next to Show preview should be set to the text Template:Val/list.

Previewing this page with Val/list is different from previewing it with other pages. You can preview your new settings on any page. Val/list is a transclusion of this page, so previewing Val/list previews this page and it previews the edit box of this page, showing all changes immediately on what only seems to be another page.

Previewing this module page on Val/list is pretty much a required step. Previewing this module page on other other pages is recommended because it can prove your changes' effects on Val itself. Just run a Show preview on the fullpagename that uses Val with your unit code. If it is in a sortable table, this is a plus.

To maintain Val units

Edit this page, using the edit button at the very top.
a your changes or additions here. The format of entries is explained below.
Below the edit box. Enter Template:Val/list into the Show preview, and test the link from the preview below. An "invalid definition" message is automatically available.
Make any further changes to Val/units, and Show preview again.
Show preview on any other fullpagename with the Val call on it.
Save your changes to this page.

Before changing or removing any Val unit codes, you can check to see how unit codes may or may not be in use on the wiki by employing {{Template usage}}. For example, to see about changing or removing unit code J.s, do a {{tlusage|val|"J.s"|0}} → hastemplate:"val" insource:/\{\{ *[Vv]al *\|[^}]*"J.s"/ prefix::. (Put the unit code in quotes.)

Testing a new unit

To test a newly added unit not used on any page, you will need to run the preview on a sandbox page you have already created. Here are all the test cases you can preview there before saving your changes here; they are the four |u= parameters:

{{Val|9|u =            }}
{{Val|9|ul =           }}
{{Val|9|u=foo|up =     }}
{{Val|9|u=foo|upl =    }}

and the sortable table:

{| class="wikitable sortable" summary="Sortable table to test Val sorting"
! Val number and unit
|-
| {{val|5|u=      }} 
|-
| {{val|3|u=      }} 
|-
| {{val|1|u=      }} 
|-
| {{val|2|u=      }} 
|-
| {{val|4|u=      }} 
|}

If your unit accepts an SI prefix you can test, say, k, m, and G, with your unit, and compare with e notations 1e3, 1e6, and 1e9 in the number. For example, Val sorts these two as equal: 1e3 m (standard e notation) and 1 km.

What to look for

The linked and non-linked markup should look exactly the same.
Navigate to the new link. It is safe: you can go back in your browser to here.
The two |up= versions should have no space in front of them.
For SI prefixes sorting 2e3 (or 2000) should be greater than k (kilo prefix).

Format of the config file

An entry defining a unit for Val is a single line starting with the unit code, followed by at least two spaces, and then a wikilink:

code [[pagename|symbol]]

The wikilink must supply the pagename and the unit symbol. (Unlike other wikilinks, this one accepts no templates at all, such as {{subsup}}.)

Also this line is a recognized entry format:

code symbol pagename

Both of these lines are equivalent and contain the same three elements (although note the difference in their order):

unit code: Unit abbreviation. Composite units have dimensions, and use a dot . to multiply or a slash / to divide and a -1 to divide (or greater) to divide powers.

unit pagename: Title (or section) of an article.

unit symbol: Standard abbreviation. The symbol is either a simple abbreviation or contains Wikipedia HTML formatting for superscript, or subscript, the multiplication dot, etc. (Templates cannot be applied here.) Always use abbreviation tags to indicate the full name of the unit. (The full name of the unit can also be hover-text via a redirect, but prefer the tag.)

You can add unit-code aliases for:

capitalization: unit codes are case sensitive
divisor units: the -2 version for inverse squared, etc., so we end up with both the slash a/b and inversion ab-1 forms. For example when adding a unit like m/s, add the m⋅s−1 version as well.
multiplier units: consider using the * version as well as the . version.

The entry is ignored if it lacks at least two adjacent space characters. The second format also takes tabs in the second delimiter in order to help with the greater need for alignment there.

Scale

A scale may be entered following the link. For example, the following defines a unit with code billion, symbol billion, link 1,000,000,000, and scale 1e9 (1×10⁹). The scale affects the hidden sort key included in the result: for example, {{val|2|u=billion}} would sort after {{val|98.7|e=3}}.

billion            billion          1,000,000,000          1e9

SI

A unit may be defined as "SI" which means that the unit code begins with an SI prefix which will be interpreted by {{convert}}. For example, the following defines an SI unit with code kV, base symbol V, and link Volt. The symbol V refers to the base unit with the SI prefix removed. A unit defined in this manner will have its sort key scaled by convert according to the SI prefix: for example, {{val|1|u=kV}} would sort after {{val|999|u=V}}. This is useful for units which are not defined in convert, or which are defined but where a link different from that specified in convert is wanted.

kV                 V                Volt                   SI

Other flags

Flag words can be entered after a tab character or two or more spaces:

ALIAS specifies that the unit's symbol is the code for a unit defined in {{convert}}}.
ANGLE identifies the unit as an "angle" so the unit is displayed after the number and uncertainty values; ANGLE also implies NOSPACE.
NOSPACE prevents the default insertion of a non-breaking space before the unit symbol.
SI specifies that the unit's symbol is for a base unit after removing the SI prefix in the unit code.

Examples

See Template:Val/list for examples.

Say you are adding c₀, the speed of light in a vacuum, for example. The following entry will define your unit code as c0, your unit symbol as ''c''0, and the unit's article as Speed of light#Numerical value, notation, and units.

c0 [[Speed of light#Numerical value, notation, and unit symbol|''c''0]]

or

c0 ''c''0 Speed of light#Numerical value, notation, and units

Then preview with Template:Val/list , check for an error message next to the new unit, and test the link you gave.

After that the page with the (saved) Val calls is used to test the linked and non-linked versions of the normal and the per units:

{{val|0.891|u=c0}} → 0.891 c₀
{{val|0.891|ul=c0}} → 0.891 c₀
{{val|0.891|up=c0}} → 0.891/c₀
{{val|0.891|upl=c0}} → 0.891/c₀

For an entire example:

Put this in a sandbox: {{val/sandboxlua|1.23|ul=wocky}} → 1.23 wocky
Edit Module:Val/units and insert a line like the following (do not save yet):
wocky wocky Jabberwocky
Under "Preview page with this module" enter Template:Val/list, and click Show preview. It shows all of Val/units in the Val/list format, as it will become when you save this page. Say there are no errors, the markup looks good, and the link navigates to the best explanation of the unit.
Then in the same way of previewing, put the fullpagename of the sandbox from step 1, and click Show preview. It shows the whole page including the val under test.
If wanted, click "Save page" to save the edit to Module:Val/units.

If you want a unit to add for practice, add one from List of common physics notations, or from SI units#Units and prefixes.

There are many examples of composite units that have their own page, so adding a unit code for one of those should link to its page.

For a new composite unit you should probably link the whole composition, not individual parts of it. At least link the largest portion which could have its own page.

The val user can compose a divisor unit on the fly from existing unit codes, and with individually linked numerator and denominator. For example:

{{val|99|ul=m|upl=d}} → 99 m/d

The val user can compose a multiplier unit on the fly by using the |end= parameter to prepend to the unit, and these can also be individually linked. For example (in geology) there is already 333 ¹⁴C yr BP to use with |end=:

{{val|333|ul=uBP|end= [[megaannum|Ma]]}} → 333 Ma ¹⁴C yr BP".

For example Val/units says

m.s-1 [[Metre per second|m⋅s−1]] linking to an article titled Metre per second, not

m.s-1 [[Metre|m]]⋅[[Second|s]]−1 which has separate links to already existing unit codes.

Alias a Convert unit

If you are here to change the link or markup of a unit, but it is not listed at Val/units, sometimes you can find the unit markup and link that you do want, already existing at Template:Convert#Units. In that case you can change the unit code to whatever you'd prefer, and it will achieve your goal. For example, if {{Val|1|C}} is going to Celsius instead of Colombs, you can define your own unit code, say "degC".

The following defines degC to refer to the unit known as °C in convert. There is no link because a link is defined at Convert.

degC               °C               ALIAS