View source for Module:Val/units/doc

This where you {{edit|Module:Val/units|configure Val units}}.  The list of Val units is published at ''[[Template:Val/list]]'', and here is the place that produces that report.  So preview {{space}} <kbd>{{big|Template:Val/list}}</kbd> {{space}} from the edit box to see your changes before saving them.  The file format and syntax are mostly self explanatory.

* The [[field separator]] is two or more spaces. 

* You can enter new units in the "Unsorted units" section if you are not sure where else it might go.

* If the same ''unit code'' is defined twice on this page, the first one overrides the later one. 

* For new entries the style guideline is ''[[Wikipedia:UNITS]]''.

* Convert and Val share units.  If you have an issue with a unit pagename or a unit symbol, and that unit is not published at Val/list, you may decide to address it at [[Template talk:Convert]].  To override entries at Convert, make an entry here.

* If you're not in a hurry, you may notice when editing Val/units that it consists of two Lua string assignments, and Lua comments. Be careful.

Questions or requests related to Val units are welcomed at [[Template talk:Val]].
For feedback specifically about the terminology or procedural steps seen on this page, please use the talk page.  

Below are the detailed procedures, examples, descriptions of testing and previewing, explanations about sorting Val expressions, and links to helpful pages.  There's also further information about Val/Convert relations.

== Introduction ==



An entry defining a [[Unit of measurement|unit]] for Val is a single line under a [[Wikipedia:section|section]] heading.<ref>Module pages don't have section editing.</ref> It starts with the '''unit code''', followed by at least two spaces and a [[WP:wikilink|link]].  If you are adding a group of related units, you can enter a blank line around them to group them in the report at Val/list. An entry is ignored if it lacks at least ''two adjacent space characters''.  

:<kbd>''code''{{spaces|4}}[<nowiki/>[ ''pagename'' | ''symbol'' ]]</kbd>

;unit code
: The keyboard typeable name of the symbol that users give Val's {{para|u}}, {{para|ul}}, {{para|up}} or {{para|upl}} parameters.
* Unit codes will be case sensitive.
* Prefer {{code|u}} for the Greek letter &mu;, if you're not sure.
* Composite units have [[Dimensional analysis#Definition|dimensions]] that multiply, divide, and apply powers to component units.  Use {{code|.}} to multiply, {{code|/}} to divide, and a signed digit for powers.  For multiplication, {{code|*}} is deprecated.  When adding a unit that includes division, consider also adding a version with multiplication by the negated power; for example, {{code|m/s2}} and {{code|m.s-2}} (for <kbd>m/s<sup>2</sup></kbd> and <kbd>m&sdot;s<sup>−2</sup></kbd>).

;unit pagename
:Title or section of an article. When linked with ul or upl,  the title or one of its [[WP:redirect|redirect]]s can expand the abbreviation for the unit.<ref>A redirect page is easy to make; there are tools on the editor toolbars.</ref>  

;unit symbol
:[[wp:V|Verifiable]], standard symbol, formatted in accordance with [[WP:UNITS]].
* Templates will not work for producing the unit symbol for input to this module; only [[Wikipedia:HTML#Formatting|Wikipedia HTML formatting]] is accepted.
* Composite units use {{code|&sdot;}} to multiply, {{code|/}} to divide, and {{tag|sup}} for powers. Division is also the unit-inversion form that multiplies a negative numbered power, for example for <kbd>m/s<sup>2</sup></kbd> and <kbd>m&sdot;s<sup>−2</sup></kbd> (from {{code|m.s-2}} and {{code|m/s2}}).
* If the hover-text just shows the abbreviation, it is not a user-friendly unit-symbol. When not linked, the unit's abbreviation can be spelled out with hover-text at the symbol by way of the ''title'' attribute of either {{tag|abbr}} or {{tag|span}}.
* For more about HTML tags and HTML symbols such as {{code|&sdot;}}, see [[Wikipedia:HTML]]. 
* For more information about marking up your unit symbol see [[WP:HTML#formatting]].
* Examples of unit codes, and hover text are at [[Template:Val/list]].

;unit code alias
: The same unit/pagename/symbol, but by way of a different unit code.  
:Unit code aliases are commonly applied for
* capitalization, to make the unit code case insensitive.
* per units, for example <kbd>m/s</kbd> and <kbd>m⋅s{{sup|−1}}</kbd>.
* Greek letters, to allow for both US keyboard and Greek-character-input applications, for example the SI prefix &mu;

;Preview page with this template/module
: A feature, similar to a sandbox and testcases, that provides a preview of how the code currently in the edit box (sandbox) will look when applied to any page (testcases).

The preview of main interest is <kbd>Template:Val/list</kbd><ref>The special relation between Val/units and Val/list is that the wikitext of Val/list is always generated by Val/units when that page is viewed, ''so'' when you '''preview page with this module''', Val/list is generated using the contents of the edit box of Val/units.</ref>, but previewing other your own page of interest with your newly added unit in a val call and in a sorting table are also part of this procedure. [[Template:Val/units/testcases]] contains Val calls for all defined Val units.

== How to add a unit ==

To maintain Val units, 
# {{edit|Module:Val/units|Edit Module:Val/units}} and make your changes.
# Preview {{space}} <kbd>{{big|Template:Val/list}}</kbd> {{space}} .
#* Look for any messages. An "Invalid definition" message is available automatically. 
#* [[Wikipedia:TESTLINK|Prove the intended link]] from the preview. 
#* Hover the mouse over the link, and read the hover-text or URL display somewhere in the browser.
# Add any unit-code aliases.
# Add any sorting if needed. Details about sorting are covered below. 
# Preview a test page. It will have template Val calls on it, and it may have a [[Help:tables#Sortable tables|sortable table]] to test sorting. [[Template:Val/units/testcases]] is a test page containing Val calls for all units.
# ''Show changes'' to prove no accidental edits occurred.
# Save the page.  Saving the page activates the changes immediately, and they go live.  You're done adding your unit.

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

'''Changing or removing existing unit codes''' is possible by employing {{tl|Template usage|Val|''code''}} to see how Val unit codes may or may not be in use on the wiki. For example, to see about changing or removing unit code <kbd>J.s</kbd>, do a 
:{{#invoke:DemoTemplate|tlusage|val|"J.s"|0}}. 
Put any unit code in quotes if it contains dash, dot, or slash{{mdash}}anything but a letter or number.  See [[Template:Val/units/test]] for a list of these searches for each Val unit.

=== Examples ===
Say you're creating a new page or revamping an old page, and discover the need for a convenient way to make several entries containing [[Speed of light|<span title="speed of light in a vacuum">''c''<sub>0</sub></span>]], and link that symbol to the page ''Speed of light''. The following entry will define your unit code as <kbd>c0</kbd>, your unit symbol as <kbd><nowiki>''c''<sub>0</sub></nowiki></kbd>, and the unit's article as ''[[Speed of light#Numerical value, notation, and units]]''.

:<kbd>c0{{spaces|2}}'''{{big|1= &#91;[ }}'''Speed of light#Numerical value, notation, and unit symbol'''{{big|{{!}}}}'''<nowiki>''c''<sub>0</sub></nowiki>'''{{big|]]}}'''</kbd>
or as explained below at [[#Advanced unit entry formats|&sect;Advanced unit entry formats]], you can also write
:<kbd>c0{{spaces|2}}<nowiki>''c''<sub>0</sub></nowiki>{{spaces|6}}Speed of light#Numerical value, notation, and units</kbd>

Then preview with ''Template:Val/list'', and 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:
*<kbd><nowiki>{{val|0.891|u=c0}}</nowiki></kbd> → {{val|0.891|u=c0}}
*<kbd><nowiki>{{val|0.891|ul=c0}}</nowiki></kbd> → {{val|0.891|ul=c0}}
*<kbd><nowiki>{{val|0.891|up=c0}}</nowiki></kbd> → {{val|0.891|up=c0}}
*<kbd><nowiki>{{val|0.891|upl=c0}}</nowiki></kbd> → {{val|0.891|upl=c0}}

For an entire example that uses the other format to make a Val/unit entry.
#Put this in a sandbox: <kbd>{<nowiki/>{val|1.23|ul='''tins'''}}</kbd> → {{val|1.23|ul=tins}}
#Edit [[Module:Val/units]] and insert a line like the following (do not save yet):
#:<kbd>'''tins'''{{spaces|3}}'''tins'''{{spaces|3}}Contins unities</kbd>
#Under "Preview page with this module" enter <kbd>Template:Val/list</kbd>, and click ''Show preview''.  It shows Val/list through the version of Val/units in the edit box. Say there are no errors, the markup and hover-text look good, and the link navigates to the unit's page.
#Then in the same way of previewing, put the [[wp:pagename|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.  There are many articles that could use a new Val unit, such as molarity at [[Resveratrol]].

Either of the test pages of these examples could have the sortable test-table shown in the next section.

== 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 {{para|u}} parameters:
<pre>
{{Val|9|u =            }}
{{Val|9|ul =           }}
{{Val|9|u=foo|up =     }}
{{Val|9|u=foo|upl =    }}
</pre>

and the [[Help:Table#Sortable_tables|sortable table]]:

<pre>
{| 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=      }} 
|}
</pre>

This table falls into place unsorted, so when 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: <code>1e3 m</code> (standard [[scientific notation#E notation|e notation]]) and <code>1 km</code>.

;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 {{para|up}} versions should have no space in front of them.
* For SI prefixes sorting 2e3 (or 2000) should be greater than k (kilo prefix).

== Advanced unit-entry format ==

In the usual format

:<code>''code''{{spaces|4}}[<nowiki/>[''pagename''|''symbol'']]</code>

the wikilink represents two fields itself, for a total of three fields per entry.
But you cannot use a wikilink for composite units that need more than one pagename.

The other record type for adding a unit entry is also three fields. It has the same three fields, but they are in a different order.
:<code>''code''{{spaces|4}}''symbol''{{spaces|8}}''pagename''</code>
This format separates each field with whitespace, and also takes tabs between fields two and three.

For a new composite unit you should probably link the whole composition, or 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:
:{{#invoke:DemoTemplate|val|99|ul=m|upl=d}}
* The val user can compose a ''multiplier'' unit on the fly by using the {{para|end}} parameter to prepend to the unit, and ''these'' can also be individually linked.  For example (in geology) there is already {{Val|333|ul=uBP}} to use with {{para|end}}:
:{{#invoke:DemoTemplate|val|333|end=&nbsp;[[megaannum|Ma]]|ul=uBP}}". 

For example [[Template:Val/list]] says
 
<code>m.s-1&nbsp;&nbsp;'''{{big|[<nowiki/>[}}'''Metre per second|m&amp;sdot;s&lt;sup>&amp;minus;1&lt;/sup>'''{{big|]<nowiki/>]}}'''</code> linking to an article titled ''[[Metre per second]]'', not 

<code>m.s-1&nbsp;&nbsp;'''{{big|[<nowiki/>[}}'''Metre|m'''{{big|]<nowiki/>]}}'''&amp;sdot;'''{{big|[<nowiki/>[}}'''Second|s'''{{big|]<nowiki/>]}}'''&lt;sup>&amp;minus;1&lt;/sup></code> which has separate links to already existing unit codes.

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

There is an optional field that goes at the end after two or more spaces or one or more tabs.  It is a flag mainly used to provide for that unit to be sorted in a table. 
Flags are mainly for sorting, and they work for either record type. Just add two or more spaces, or one or more tabs, and then the flag field.  (Optional flags ALIAS and NOSPACE and ANGLE are for even more advanced users.  See [[#Advanced unit flags|&sect;Advanced unit flags]] below.)

Using SI requires that the unit symbol compare precisely to the unit code, and 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. 

=== Sorting ===
{{details|topic=sorting |Help:sorting }}
{{details|topic=scaling |Template:Ntsh}}

Val's sorting scale factor is for comparison to other Val units that might be sorted with it. 

Where [[Help:Sorting|Sorting]] is done on the wiki, it is done in [[Help:table#Sortable tables|sortable tables]].  
Val entries in a sortable table will need a fourth field sorting flag.  It can be a number, an equation, or an <kbd>SI</kbd>, but it flags the same function: a wikitable sorting "scale".  

To display the sort key use {{para|debug|yes}}.  For example

*<code><nowiki>{{val|999|u=uV|debug=yes}}</nowiki></code> → <span class="nowrap"><span style="border:1px solid;display:inline;" class="sortkey">6996998999999999999♠</span>999&nbsp;µV</span>
*<code><nowiki>{{val|99|u=V|debug=yes}}</nowiki></code>   → <span class="nowrap"><span style="border:1px solid;display:inline;" class="sortkey">7001990000000000000♠</span>99&nbsp;V</span>
*<code><nowiki>{{val|1|u=kV|debug=yes}}</nowiki></code>   → <span class="nowrap"><span style="border:1px solid;display:inline;" class="sortkey">7003100000000000000♠</span>1&nbsp;kV</span>

==== Scale ====

For scaling a unit to sort properly, you need to pick a number for a sorting factor. 
There are numerous examples at [[Template:Val/list]] and at [[Template:Val/sortkey/unit]]. A [[system of units]] will have its base units, for example 1 bit; then the scale for sorting a kilobyte 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 <kbd>billion</kbd>, symbol <kbd>billion</kbd>, link [[1,000,000,000]], and scale <kbd>1e9</kbd> ({{val|1|e=9}}).  After the following entry is saved to the database
<pre>
billion            billion          1,000,000,000          1e9
</pre>
<nowiki>{{val|2|u=billion}}</nowiki> would start sorting after <nowiki>{{val|98.7|e=3}}</nowiki>.

==== SI flag ====
{{common metric prefixes}}
SI is used because it scales Val expressions automatically, and it is a clean indicator that the unit will sort properly. It correctly scales any SI prefix for sorting, but not other unit codes.

For SI the unit symbol will not accept HTML, but will accept &mu;. HTML is not accepted at this time because in order to validate the entry, the unit code must differ from the unit symbol by exactly one valid [[SI prefix]]. If there is no difference, or too much difference, it is an invalid definition for sorting purposes.  The exception is for the Greek letter &mu;: if you used a character input application to "install" the Greek letter <code>&mu;</code> in your symbol, for your "easy to type" unit code, {{key|u}}, these two are not a character mismatch.

All unit entries that use SI will have the same base unit as the symbol at Val/units, but they will display properly at Val/list.

For example, kilo is a thousand, but you're defining km2 for kilometers squared, and need HTML.  You can't use SI with HTML, so use 1000*1000, or 1000000 in the sorting field. Use [[e notation|1e-6]] or 0.000001 or 1/100000 instead. 

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, like ''Meter'' in the example, may have their own article, but usually all go to the base unit's pagename.  Here is how ''meter'' is defined.

<pre>
m     [[Metre|m]]         SI
cm    [[Centimetre|m]]    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
</pre>

The information that was in the unit symbol is now fully specified in, and exhibited at, the unit code.  <code>SI</code> 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.

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.
:<code>kV&nbsp;&nbsp;&nbsp;V&nbsp;&nbsp;&nbsp;Kilovolt&nbsp;&nbsp;&nbsp;&nbsp;SI</code>
:<code>µV&nbsp;&nbsp;&nbsp;V&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;SI</code>
:<code>uV&nbsp;&nbsp;&nbsp;V&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;SI</code>
Now <nowiki>{{val|1|u=kV}}</nowiki> will sort after <nowiki>{{val|999|u=V}}</nowiki> 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:
:<code>kV&nbsp;&nbsp;&nbsp;kV&nbsp;&nbsp;&nbsp;Kilovolt&nbsp;&nbsp;&nbsp;&nbsp;1e3</code>
:<code>µV&nbsp;&nbsp;&nbsp;µV&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;1e-6</code>
:<code>uV&nbsp;&nbsp;&nbsp;µV&nbsp;&nbsp;&nbsp;Microvolt&nbsp;&nbsp;&nbsp;1e-6</code>
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 {<nowiki/>{Val|1|C}} is going to Celsius instead of Coulombs, 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.
<pre>
degC               °C               ALIAS
</pre>

== File format ==

If you want to reorganize sections here, note that the two lines <code>local builtin_units</code> and <code>local builtin_units_long_scale</code> require a blank line after them.  The section [[Long and short scales|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.

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

* A "unit alias" is when Val alias a Convert unit code. 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 {{tl|Val/list}}, you can check for it at {{tl|Val/unitsfromconvert}}, or at {{tl|Convert#Units}}

For spacing and aliasing: 
*<code>ALIAS</code> specifies that the unit's symbol is the code for a unit defined in {{tlf|convert}}}.
*<code>NOSPACE</code> prevents the default insertion of a non-breaking space before the unit symbol.

*If you see the <code>ANGLE</code> flag, this identifies those special units that must displayed not only after the main Val number, but also after its [[uncertainty#Measurements]] numbers.(<code>ANGLE</code> also implies <code>NOSPACE</code>.)

== 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 {{tl|Convert}}. 
* 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 <kbd>degC</kbd> and for <kbd>degF</kbd>.
* 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 {{tlf|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. [[Module:Convert/data|An entry at Convert]] is defined as a multi-line, multi-attribute Lua table with its attendant syntax, and inside a larger Lua script.  Therefore Convert is more conservative about adding units.  Val may be more liberal in this respect if only because unit entry is simpler and "wikified".  Therefore [[WP:Be bold]]. Bold customization may be a worthwhile risk at Val/units, or it may get removed. 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.

== Notes ==
{{refs}}

== See also ==
* [[Module:Val]]
* [[Template:Val/units/test]]
* [[Template:Val/units/testcases]]
* [[Template:Val/units/loadtest]]
* [[Template:Val/unitsfromconvert]]

<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
<!-- Categories below this line, please; interwikis at Wikidata -->

}}</includeonly>