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. Here you can easily add or remove a Val unit, or modify its link or markup, as seen at Val/list.

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

Although units used in articles have standards of markup and link, here you could even alias a unit for your own use on other pages that, for any special occasions you care to imagine for instances where you personally want those instances where the unit code you give Val would, say, colorized the unit, or any other such markup available in the WP:HTML.

Convert and Val share units in the following way. Val displays units of measurement, so Val could need any or all units. Some of the unit codes Val accepts are manage by {{Convert}}, but not all units of measurement are needed in conversions, so Val needs all of Convert's units and some of its own. Convert and Val unit codes are mostly identical.

Anyone can just add a unit here, and it will work for Val. You don't really need to know all the gory details. But here they are.

Given any unit, the only differences between Val and Convert could be that the unit code is different (rarely, such as for C and F).
Given any unit code, the difference between Val and Convert could be the actual unit reference, and then the unit code results in unwanted markup or linkage; the two templates could differ entirely for that unit code.
Both Convert and Val can alias there own unit codes, and Val can alias Convert's unit codes. An alias references a unit code, and so an alias can change the markup, the link, or both.
Here, for any given unit code, you can override Convert, alias that unit code from Convert, or alias one of Val's unit codes for your own markup for your own use anywhere on the wiki.
If your unit code is not listed at {{Val/list}}, you can check for it at Template:Convert#Units, or discuss adding it or changing it at {{Convert}} (talk). To edit Convert's units yourself, follow the instructions at Module:Convert/data. At Convert the procedure for defining a unit is much more involved than it is here, because there every unit defined must reference each associated unit and the conversion factor.

Units on this page may be entered under:

local builtin_units for normal units, or under
local builtin_units_long_scale for long scale units.

You can enter any units in the "Unsorted units" section if you are not sure.

Defining a unit

Before saving changes to this page, you can test how the changes made here effect other pages. Here, that test is a Show preview that requires a fullpagename.

Previewing this page with Val/list is different from previewing it with other pages. 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 seems to be "another" page. But previewing this page can only test your changes to the markup and link of units.

Previewing other pages can test how your changes effect Val. Just run a Show preview on the page that uses your Val 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. To be thorough, you can test all four |u= parameters there before saving your changes here:

{{Val|1|u =      }}
{{Val|1|ul =     }}
{{Val|1|up =     }}
{{Val|1|upl =    }}

To maintain Val units:

Edit this page, Module:Val/units. See below for the format of entries.
Show preview on Template:Val/list and check the markup and link you added, and for any "invalid definition" errors next to your added unit.
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.

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:

unit code [[pagename|HTML]]

The wikilink must supply a pagename and Wikipedia HTML formatting. The pagename is the unit's article or section of an article, and the HTML formatting recreates the standard unit symbol.

Also this line is a recognized entry format:

unit code HTML pagename

It contains the same three elements: unit code, unit symbol, and title of the unit's article, although note the difference in the order of the elements.

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

To see all of Val's units visit Template:Val/list.

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.

Alias a Convert unit instead

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