Module:Val/units/doc

This is a documentation subpage for Module:Val/units.
It may contain usage information, categories and other content that is not part of the original module page.

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 a wikilink that has the unit's pagename but labels the link with the unit's standard abbreviation.

Anyone can just add a unit here, and it will work for Val. Many details are given in the next section in there order of importance.

Details

For such a simple and quick operation as editing Val units by just mimicking the existing format when you get there, there sure is a lot of information here. It has to do with professional touches like thorough testing, and adding features to the unit. Anyone can get as involved with Val units as they wish, because here are all the gory details, in order of importance.

Important

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

If the same unit code is defined twice on this page, the first one overrides the later 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.

For help, leave a remark at Template talk:Val/list. If you're in a hurry, Convert and Val have very active talk pages, and they share units, so you may escalate to Template talk:Val, and even to Template talk:Convert, to get answers.

File format

The file format is two Lua strings and a return statement with them in it: a string in quotes [=[ ... builtin_units ... ]=], and another string in quotes [=[ ... builtin_units_long_scale ... ]=]. The first string, builtin_units, is short-scale, second string is long scale. The reason there are two strings is because of the difference between British and US terms surrounding "billion", "billionth", etc.

For each string there must be a blank line before the first line of the string and after the last line of the string. In other words the first two and last two characters of each string must be newlines.

There is one record per line, starting in first column, having 2-4 fields. The field separator is two or more spaces. Between first and second fields, use two or more spaces. Between all other fields, use two or more spaces, or one or more tabs. Entries without two spaces in them are ignored.

Advanced unit flags

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.
If a different unit code here is assigned to the same unit symbol and unit pagename, (say, as a copy of the previous entry) it will work as an alias.

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}}

For spacing and aliasing:

ALIAS specifies that the unit's symbol is the code for a unit defined in {{convert}}}.
NOSPACE prevents the default insertion of a non-breaking space before the unit symbol.

If you see the ANGLE flag, this identifies those special units that must displayed after the number and uncertainty values.(ANGLE also implies NOSPACE.)

Interaction with Convert

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 they are for degC and for 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.

Sorting functionality is handled for Val by {{convert}}.)

Wikify Val units

Bold 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.
If you want to reorganize sections here, note that the two lines local builtin_units and local builtin_units_long_scale require a blank line after them. The section long scale, with all the units like "billions" and "trillions", is under the latter, near the bottom of the page. All the rest of the units are in the former.

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.

A preview on Val/list is required, and previewing this module on other pages is recommended because it can prove your changes through Val, not just Val/units. Just run another Show preview on the fullpagename that uses Val with your modified unit code entry. If that fullpagename also has your Val unit code in a sortable table, this is a plus for a test through Val.

To maintain Module:Val/units:

Edit this page.
Make your changes or additions. The format is explained below.
Show preview with Template:Val/list and view your changes. An "invalid definition" message is available automatically. Visit the link to the unit pagename, and return back in your browser.
Make any further changes, and Show preview again.
Add unit-code aliases and preview as before.
Add sorting scale factors if wanted, and preview as before. Look for errors.
Show preview on any other fullpagename with the Val call on it.
Show changes, and then 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 an entry

An entry defining a unit for Val is a single line inside a section heading. It starts with the unit code, followed by at least two spaces.

There are two record types:

One record type is a wikilink:

code [[pagename|symbol]]

The wikilink must supply the unit pagename and the unit symbol. The field separator is two or more spaces.

The other record type is three fields:

code symbol pagename

Both of these lines convey the same information, having the same three elements (although note the difference in their order):

unit code: Unit keyboard abbreviation. The easily typeable name.

unit pagename: Title or section of an article.

unit symbol: Standard symbol as per the MoS or verifiability. The symbol is either like unit code when it's just a letter or two, or contains Wikipedia HTML formatting with numbers and other symbols. (Templates cannot be applied here.)

Composite units, which will have dimensions, use a dot . to multiply or a slash / to divide. Add unit-code aliases for the slash (division) that convey the same information inline: for example, add the -2 version for inverse squared units. 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. Add aliases for multiplier units only rarely.

Unit codes are case sensitive. You can add unit code aliases for capitalization.

An entry is ignored if it lacks at least two adjacent space characters. The "all-fields" format also takes tabs between fields two and three.

Making a unit code and a unit symbol

For more about HTML tags and symbols see Wikipedia:HTML. There you'll learn about the ... superscript and ... subscript tags and the ⋅ symbol.
For more about style issues, see MOS:NUM.
The hover text of the linked unit symbol (requires JavaScript) should be the full name out the abbreviated unit. This can be done by virtue of the article title, a redirect title, or by way of the title attribute of either <abbr>...</abbr> or ....

The unit code uses a period (or dot) to translate to the unit symbol &sdot. The standard unit symbol letter Greek mu, for the micro SI prefix, is the letter u, such as um for micrometer.

Flags

There is an optional field that goes at the end after two or more spaces. It is a flag, mainly used to provide for that unit to be sorted in a table. Tabs are accepted in both entry formats to apply the fourth field.

Flags are mainly for sorting, and they works for either record type. Just add two or more spaces and the the flag field. (Optional flags ALIAS and NOSPACE and ANGLE are for advanced users.)

Using SI requires that the unit symbol compare precisely to the unit code, so never allows HTML or other characters in the symbol. Any difference between the unit symbol and unit code must be an SI prefix, such as k, M, or G. A space at the end of an entry is an error. No space at each EOL.

The module must be told directly about sorting factors, spacing, and aliasing for a unit code.

At the end of an entry, after the given unit pagename plus a tab character or two or more spaces, any of several indicators may be placed. This works for either of the two entry formats.

Sorting

Where Sorting is done on the wiki, it is done in sortable tables. Whether the flag is a number or an equation or the letters SI, it flags the same function: a wikitable sorting "scale".

To display the sort key use |debug=yes. For example

{{val|999|u=uV|debug=yes}} → 6996998999999999999♠999 µV
{{val|99|u=V|debug=yes}} → 7001990000000000000♠99 V
{{val|1|u=kV|debug=yes}} → 7003100000000000000♠1 kV

Scale

The term sorting "scale" isn't used at Help:sorting or Template:Ntsh. The sorting scale factor is for comparison to the like units that it might be sorted with, so go with that.

How to pick a number for a sorting factor.

First of all, look at the other entries to get an idea of how its done. A system of units will have its base units, for example 1 bit; then the scale for sorting a kilibyte unit is then 8000 (eight bits per byte, times a kilo, or thousand). Or a year scale is seconds so that all times sort by seconds, which is a base unit. In general the scale shows to be "base unit" of the same type times the "SI prefix", and if it's not that simple, then the unit system's number has associated a number to it, such as Avogadro's number.

For example, the following defines a unit with code billion, symbol billion, link 1,000,000,000, and scale 1e9 (1×10⁹). After the following entry is saved to the database

billion            billion          1,000,000,000          1e9

{{val|2|u=billion}} would start sorting after {{val|98.7|e=3}}.

SI

Metric prefixes in everyday use
v
t
e
Prefix	Symbol	Factor	Power
tera	T	1000000000000	10¹²
giga	G	1000000000	10⁹
mega	M	1000000	10⁶
kilo	k	1000	10³
hecto	h	100	10²
deca	da	10	10¹
(none)	(none)	1	10⁰
deci	d	0.1	10⁻¹
centi	c	0.01	10⁻²
milli	m	0.001	10⁻³
micro	μ	0.000001	10⁻⁶
nano	n	0.000000001	10⁻⁹
pico	p	0.000000000001	10⁻¹²

Whether the sorting flag is a number, an equation, or SI, it flags the same function: a wikitable sorting "scale". The difference between the three types of sorting flags are that SI can't accept HTML. This is because a unit code that is flagged with the SI designation is subjected to a difference calculation comparing it to its unit symbol, and the result must be a valid SI prefix. If it is zero (no difference) it is an invalid definition for sorting purposes; although it will display only the base unit at Val/list, it will display properly on a test page such as Template:Val/units/testcases because it will display the unit code in place of the unit symbol. The reason SI is used at all is because it and factors automatically, not so much that it presents well at Val/list. SI is a clean indicator. It correctly scales any SI prefix for sorting, but not other unit codes.

Examples. If you "installed" the Greek letter 𝜇 in your symbol, for your "easy to type" unit code, u, these two are currently a character mismatch to the SI function. Use 1e-6 or 0.000001 or 1/100000 instead. For example, kilo is a thousand, but you're defining km2 for kilometers squared. You can't use SI, so use 1000*1000, or 1000000 in the sorting field.

If the unit you are maintaining has SI prefixes and they are all likely to be sorted in a table, add up to twelve entries, one for each common SI unit. Some of these may have there own article, but usually all go to the base unit's pagename. Here is how meter is defined. Note that the base unit does not need the SI sort-marker.

m     [[Metre|m]]
cm    [[Centimetre|mm]]   SI
dam   [[Decametre|m]]     SI
dm    [[Decimetre|m]]     SI
hm    [[Hectometre|m]]    SI
km    [[Kilometre|m]]     SI
Mm    [[Megametre|m]]     SI
mm    [[Millimetre|m]]    SI
um    [[Micrometre|µm]]   1/1000000
µm    [[Micrometre|m]]    SI
nm    [[Nanometre|m]]     SI
pm    [[Picometre|m]]     SI

The information that was in the unit symbol is now fully specified in, and exhibited at, the unit code. SI specifies that the unit's symbol has been transformed from a symbol to a string for use in string comparison that will finally result in calculating a sorting factor. It conveniently uses the idea that the unit code is often equal to the symbol, especially with SI units. The field definitions are sacrificed for a simplicity in the user presentation, user calculation, and user entry. It keeps definitions visible, at the expense of having to decode the unit entry by shifting the symbol to the first field and merging it with the now-identical unit-code. The next example makes this clear.

In the other format, the following defines three unit codes for volts, V for sorting. V is the base unit with the SI prefix removed. A unit code defined in this manner will have its sort key scaled by the software according to the SI prefix produced by the difference between the unit code and unit symbol.

kV V Kilovolt SI

µV V Microvolt SI

uV V Microvolt SI

Now {{val|1|u=kV}} will sort after {{val|999|u=V}} without having to resort to using a number, and with the clean representation at Val/list.

The symbol column shows "V" for each, but it is not the symbol—it is the base unit after removing the SI prefix so convert can work out what is intended to be the prefix. The following would give identical results:

kV kV Kilovolt 1e3

µV µV Microvolt 1e-6

uV µV Microvolt 1e-6

As you can see, without "SI", you define both the symbol, and the scale. You define the symbol with HTML or the Greek letter or other symbol, and you define the scale with a number or an equation. When "SI" is used, convert just does the right thing for the symbol and scale.

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

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|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 the page. Say there are no errors, the markup and hover-text look 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.
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.