Template:Val/doc: Difference between revisions

From Zoophilia Wiki
Jump to navigationJump to search
meta>Jimp
Ookami (talk | contribs)
m 315 revisions imported
 
(124 intermediate revisions by 32 users not shown)
Line 1: Line 1:
{{Documentation subpage}}
{{Documentation subpage}}
<includeonly>{{High-use|2,000+}}</includeonly>
{{High-use| 16851 }}
{{Intricate template}}
{{COinS safe|n}}
<!-- EDIT TEMPLATE DOCUMENTATION BELOW THIS LINE -->
{{Lua|Module:Val}}


This template is used to easily present values in [[scientific notation]], including uncertainty and/or units, as prescribed by Wikipedia's [[WP:MOSNUM|Manual of Style]]. It wraps the entire result in a {{tl|nowrap}} block, so that it never gets broken into separate pieces at the end of a line. (See [[WP:NBSP]] for more information on the usage of non-breaking spaces.)
This template is used to easily present values in [[scientific notation]], including uncertainty and/or units, as prescribed by Wikipedia's [[WP:MOSNUM|Manual of Style]].
 
== Introduction ==
 
Val specializes in numeric ''values'', especially those with [[scientific notation]]s, [[uncertainty#Measurements|uncertainty notation]]s, and those with measurement ''values'' with physical units. Because these expressions are covered by the Manual of Style, Val provides the stylized output for you, and keeps them from wrapping across lines.
 
Express a numeral:
* <code>&#123;{val|123456.78901}}</code> &rarr; ''value'', formatted with gaps: {{val|123456.78901}}, or with {{para|fmt|commas}} &rarr; {{val|fmt=commas|123456.78901}}
* <code>&#123;{val|''number''|''number''}}</code> &rarr; ''value'' ± ''uncertainty'',  like {{val|fmt=commas|123478|56}}
* <code>&#123;{val|''number''|{{hilite|(}}''number''{{hilite|)}}}}</code> &rarr; ''value''(''uncertainty''), like {{val|fmt=commas|12345|(56)}}
* <code>&#123;{val|''number''|''number''|''number''}}</code> &rarr;''value'' {{su|p=+uncertainty|b=−uncertainty}} like {{val|fmt=commas4|1234|+56|-78}}
 
Express a measurement value: {{#invoke:DemoTemplate|val|4|ul=m2}}. The  <kbd>m2</kbd> is a "unit code" that Val uses to lookup the link to the unit's article, and the formatting of the unit symbol.  Val links the units to the page it has on file for them.  See {{tl|Val/list}}.
 
There are a large number of unit codes that Val understands and keeps "up to code".  A unit code is the just abbreviated unit name, but these can get quite involved for a compound or composite unit, with "multipliers" or "dividers".  See [[Module:Val/units]].
 
Some unit-code flexibility is provided by having four parameters to work the unit-code system: whether to link one or not, (see ''[[WP:Overlinking|Overlinking]]''), and whether to link the numerator or denominator of a unit ratio separately.
* <code>&#123;{val|''number''|'''ul='''''unit code''}}</code> &rarr; ''number {{font color|blue|symbol}}'', such as {{val|9.8|ul=km2}}
* <code>&#123;{val|''number''|'''u='''''unit code''}}</code> &rarr; ''number&nbsp;symbol'', such as {{val|9.8|u=km2}}
* <code>&#123;{val|''number''|'''u='''''unit code''|'''u{{hilite|p}}l='''''unit code''}}</code> &rarr; ''number''&nbsp;symbol{{big|{{hilite|/}}}}{{font color|blue|symbol}}, such as {{val|9.8|u=gal|upl=min}}
* <code>&#123;{val|''number''|'''ul='''''unit code''|'''u{{hilite|p}}='''''unit code''}}</code> &rarr; ''number''&nbsp;{{font color|blue|symbol}}{{big|{{hilite|/}}}}''symbol'', such as {{val|9.8|ul=parsec|up=year}}
 
To bypass the unit code system, if {{para|u}} does not recognize your unit code, it will accept any wikitext and render it as usual.
* {{#invoke:DemoTemplate|val|5.4|u=[[kg]]&sdot;[[meter|m]]/s<sup>2</sup>}}
* {{#invoke:DemoTemplate|val|7.6|u=[[metre per second squared|m/s<sup>2</sup>]]}}
See [[Module:Val/units]] for how to add units to the unit code system.
 
Sometimes a number and unit code is not enough.  A prefix or suffix are also available, {{para|p}} and {{para|s}}.
* {{#invoke:DemoTemplate|val|7600|u=  C&sdot;Ga  |p= > | s= < }}
* {{#invoke:DemoTemplate|val|7600|u=C|p=<span style="color:green"><sup>|s=</sup></span>}}
 
See {{tl|val/testcases}} to learn the val parameters by an example. It is comprehensive, and there are over 100 examples.


== Arguments ==
== Arguments ==
{{details|Help:Template#Parameters}}
Val takes three unnamed parameters.  The first is always the numeric value. When the second and third are numbers they become the various uncertainty notations, but the second unnamed parameter can also serve to ''grammatically join'' the first and third numbers.


There are four ways this template can be used:
Val clears surrounding spaces in its unnamed parameters.
* <code><nowiki>{{</nowiki>val|''number''<nowiki>}}</nowiki></code> - for displaying values without uncertainty/significance.
* <code><nowiki>{{</nowiki>val|''number''|''uncertainty''<nowiki>}}</nowiki></code> - for displaying values with uncertainty, like so: {{val|1234|56}}.
* <code><nowiki>{{</nowiki>val|''number''|''upper uncertainty''|''lower uncertainty''<nowiki>}}</nowiki></code> - for displaying values with uncertainty, like so: {{val|1234|+56|-78}}.
* <code><nowiki>{{</nowiki>val|''number''|(''significance'')<nowiki>}}</nowiki></code> - for displaying values with significance, like so: {{val|1234|(56)}}.
They all take roughly the same arguments


{|
{|cellspacing="15" cellpadding="0"
| style="vertical-align:top;" | '''1''' || The value (must be a valid number)
| style="vertical-align:top;text-align: center;" | '''1st''' or {{para|1}} || A number in [[radix point|decimal point]] notation or in [[e notation]].  The main basis of the Val expression.<br />
|-
{{#invoke:DemoTemplate|val|1234567.1234567}}<br />
| style="vertical-align:top;" | '''2'''  || The (upper limit of) uncertainty (must be a valid number) or significance (must be a valid number in parenthesis)
{{#invoke:DemoTemplate|val|.1234}} {{spaces|19}}(adds the zero)<br />
{{#invoke:DemoTemplate|val|+1234}} {{spaces|20}}(displays the plus) <br />
{{#invoke:DemoTemplate|val|-1234}} {{spaces|20}}(replaces the [[hyphen-minus]] with a [[minus sign]])<br />
{{#invoke:DemoTemplate|val|12e34}} {{spaces|15}}([[Scientific notation#E notation|E notation]])<br />
|-
|-
| style="vertical-align:top;" | '''3'''  || The lower limit of uncertainty (must be a valid negative number)
|style="vertical-align:top;text-align: center;"| {{para|fmt}}
| By default, numbers are formatted with gaps separating groups of three digits in both integer and fractional part.<br />
However, by default, four-digit integers are not formatted; use {{para|fmt|gaps}} to force gaps.<br />
Use {{para|fmt|commas}} to delimit the integer part of the number with commas.<br />
Use {{para|fmt|none}} for no formatting (no gaps or commas).<br />
{{#invoke:DemoTemplate|val|1234567.1234567}}<br />
{{#invoke:DemoTemplate|val|1234567.1234567|fmt=commas}}<br />
{{#invoke:DemoTemplate|val|1234}}<br />
{{#invoke:DemoTemplate|val|1234|fmt=gaps}}<br />
{{#invoke:DemoTemplate|val|1234.5}}<br />
{{#invoke:DemoTemplate|val|1234.5|fmt=none}}
|-
|-
| style="vertical-align:top;" | '''e'''  || The exponent for the power of 10 (optional). This will show up in the result as: <span style="margin-left:0.25em;margin-right:0.15em">×</span>10{{su|p=e}}.
| style="vertical-align:top;text-align: center;" | {{para|end}} || Put something at the end of the main number (before anything else that might follow). <br />
:Values (arguments '''1'''–'''3''' and '''e''') are run through code copied from {{tlf|delimitnum}} for readability, except for argument '''2''' when it is surrounded by parenthesis. '''This causes an error for large numbers, numbers that require high precision.''' Correction will require changes to the Wikipedia software.
{{#invoke:DemoTemplate|val|11|end=<END>}}<br />
{{#invoke:DemoTemplate|val|11|22|end=<END>}}<br />
{{#invoke:DemoTemplate|val|1111|(22)|end=<END>}}<br />
{{#invoke:DemoTemplate|val|11|22|33|end=<END>}}<br />
{{#invoke:DemoTemplate|val|11|ul=m/s|end=<END>}}
|-
|-
| style="vertical-align:top;" | '''sortval'''  || Alternative sorting factor to ''1''
| style="vertical-align:top;text-align: center;" | '''2nd''' or {{para|2}} || [[uncertainty#Measurements|Uncertainty]] in either format.<br />
{{#invoke:DemoTemplate|val|11|22}}<br />
{{#invoke:DemoTemplate|Val|11|(22)}}<br />
A conjunction to join two numbers. Useful for ranges, grammatical output, etc.<br />
{{#invoke:DemoTemplate|val|11|-|33}}<br />
{{#invoke:DemoTemplate|val|11|–|33}}<br />
{{#invoke:DemoTemplate|val|11|,|33}}<br />
{{#invoke:DemoTemplate|val|11|by|33|e=9}}<br />
{{#invoke:DemoTemplate|val|11|and|33|end=$}}<br />
{{#invoke:DemoTemplate|val|11|or|33}}<br />
{{#invoke:DemoTemplate|val|11|to|33}}<br />
{{#invoke:DemoTemplate|val|11|x|33}}<br />
{{#invoke:DemoTemplate|val|11|×|33}}<br />
{{#invoke:DemoTemplate|val|11|/|33|ul=m/s}}<br />
Note that for dashes or x's, the various kinds all obtain one properly styled output.
|-
|-
| style="vertical-align:top;" | '''u''' / '''ul'''  || Activate units and any markup / with a link to a page about the unit (optional / optional)
| style="vertical-align:top;text-align: center;" | '''3rd''' or {{para|3}}
| Asymmetric uncertainty.<br />
{{#invoke:DemoTemplate|Val|11|22|33}}
|-
|-
| style="vertical-align:top;" | '''up''' / '''upl''' || Construct units, and this is the "per" unit that is the denominator / with a link to a page about the denominator (requires numerator from '''u''' or '''ul''')
|style="vertical-align:top;text-align: left;"|{{para|errend}} or {{para|+errend}} and {{para|-errend}}|| Appends something after an uncertainty.<br />
:Units for the number, specified by '''u''' and '''ul''' (and '''up''' and '''upl'''), are replaced by a more aesthetically pleasing HTML representation and can get a link ('''ul''' and '''upl''' only) if they are in the list found in {{tl|val/unitswithlink}} or if they are supported by {{tl|convert}}). You can specify units using just '''u'''; a good example is "ul=m/s", which gets translated to "[[Meter per second|m·s<sup>−1</sup>]]", or you can use '''u''' and '''up''', as in "u/up"; a good example is "ul=m|up=s", which gets translated to "[[Metre|m]]/s".
{{#invoke:DemoTemplate|val|11|22|errend=<Errend>}}<br />
{{#invoke:DemoTemplate|val|11|22|33|-errend=<−Errend>|+errend=<+Errend>}}
|-
|-
| style="vertical-align:top;" | '''us''' / '''ups'''  || Alternative unit code for sorting.
| style="vertical-align:top;text-align: center;" | {{para|u}} or {{para|ul}} || [[Template:Val/units|The unit code]].  Val adds a space and the unit.<br />
{{para|ul}} Link the unit.<br />
{{para|u}} Don't link the unit. Also accepts [[help:wiki markup|wiki markup]] in lieu of a unit code.<br />
{{#invoke:DemoTemplate|val|11|ul=m}}
|-
|-
| style="vertical-align:top;" | '''p'''  || A prefix for the value (such as ∆, , etc.; optional).
| style="vertical-align:top;text-align: center;" | {{para|up}} or {{para|upl}} || A unit code, but instead of a space Val adds a slash and the unit, a "per" unit (the denominator), to form a ratio.<br />
{{para|upl}} Link the per unit.<br />
{{para|up}} Don't link the per unit.<br />
The ratio can be of two unit codes, or a prefix and a unit code. Val will add parentheses to disambiguate, if a unit code has a dot or a slash.<br />
{{#invoke:DemoTemplate|Val|11|ul=J/C|upl=F/m}}<br /> {{#invoke:DemoTemplate|Val|11|p=$|upl=acre}}<br />
{{#invoke:DemoTemplate|Val|11|ul=km/s|upl=Mpc}}<br />
{{#invoke:DemoTemplate|Val|11|ul=kg.m|upl=s-2}}
|-
|-
| style="vertical-align:top;" | '''s''' || A suffix for the value (such as %, optional).
| style="vertical-align:top;text-align: center;" | {{para|p}} || Prefix the entire Val expression.  Non-spaced, but accepts markup.<br />
:Prefixes (specified by '''p''') and suffixes (specified by '''s''') are put in front of or behind the value ''as is'': this includes spaces. They are inside the ''nowrap'' block and will always be on the same line as the value. The parameters that previously provided this functionality ('''h''' for header and '''f''' for footer) are ''deprecated'' and will be ignored.
{{#invoke:DemoTemplate|Val|11|22|ul=m/s|p=<Prefix>}}<br />
{{#invoke:DemoTemplate|Val|11|22|ul=m/s|p=<Prefix>&nbsp;}}
|-
|-
| style="vertical-align:top;text-align: center;" | {{para|s}}  || Suffix the entire Val expression. Non-spaced, but accepts markup.<br />
{{#invoke:DemoTemplate|Val|11|22|ul=m/s|s=<Suffix>}}<br /> {{#invoke:DemoTemplate|Val|11|22|ul=m/s|s=&nbsp;<Suffix>}}
|-
|-
| style="vertical-align:top;" | '''end''' || Appends something after the main value. For example, <nowiki>{{val|123.24|end=...}}</nowiki> gives {{val|123.24|end=...}}
| style="vertical-align:top;text-align: center;" | {{para|e}}
| Exponent. Val alternatively accepts e notation in the first parameter; these are mutually exclusive (see "1st" argument above).<br />
{{#invoke:DemoTemplate|Val|11|22|33|e=11}}<br />
{{#invoke:DemoTemplate|Val|11e11|22|33}}
|-
|-
| style="vertical-align:top;" | '''errend''' || Appends something after the uncertainty. For example, <nowiki>{{val|123.23|end=...|2.34|errend=...}}</nowiki> gives {{val|123.23|end=...|2.34|errend=...}}
| style="vertical-align:top;text-align: center;" | {{para|long scale}}  || Usually a unit is the short [[ton]] and [[billion]] means {{val|1|e=9}}. But there are long versions of these units and others. Use {{para|long scale|on}} to assign your unit to the long scale instead. The unit code's link will change and it will sort differently in tables. "See [[Long and short scales]]".
|-
|-
|align=top| {{nowrap|'''+errend'''}} & {{nowrap|'''-errend'''}} || Appends something after the positive/negative uncertainties. For example, <nowiki>{{val|123.23|end=...|+2.34|+errend=...|-1.23|-errend=...}}</nowiki> gives {{val|123.23|end=...|+2.34|+errend=...|-1.23|-errend=...}}
| style="vertical-align:top;text-align: center;" | {{para|nocategory}} || If set to any value, errors in the use of this template will not cause the page to be added to the [[:Category:Pages with incorrect formatting templates use|Pages with incorrect formatting templates use]] category. This is useful for documentation and test pages that do not need to be fixed.
|-
|align=top| {{nowrap|'''fmt'''}} || Allows alternative formatting using commas to the left of the decimal point as opposed gaps either side. For example, <nowiki>{{val|123123.123123|fmt=commas}}</nowiki> gives {{val|123123.123123|fmt=commas}}
|-
| style="vertical-align:top;" | '''nocategory''' || If set to any value, errors in the use of this template will not cause the page to be added to the [[:Category:Pages with incorrect formatting templates use|Pages with incorrect formatting templates use]] category. This is useful for documentation and test pages that do not need to be fixed.
|-
| style="vertical-align:top;" | '''long scale'''  || Use {{para|long scale|on}} to link and sort {{para|u|billion}} etc. according to the "[[long and short scales|long scale]]".
|}
|}
See {{tl|val/testcases}} for a list of examples of the correct output of {{tl|val}} and the errors it may return when incorrectly used.


== Errors ==
== Errors ==


There is strict checking on the validity of arguments; any incorrect use will result in an error, which is displayed using {{tl|FormattingError}}. Pages that contain incorrect use of this template will show up on [[:Category:Pages with incorrect formatting templates use]].
There is strict checking on the validity of arguments; any incorrect use will result in an error, which is displayed using {{tl|FormattingError}}. Pages that contain incorrect use of this template will show up on [[:Category:Pages with incorrect formatting templates use]].
Val checks for unsupported parameters and gives a relatively subtle warning if found. See [[:Category:Pages with incorrect formatting templates use|tracking category]] to track any of these improper usages on existing on the wiki. Hold the mouse over "warning" to see details.  Here is what warnings look like:
*<code><nowiki>{{val|1.23|exp=6|u=m/s}}</nowiki></code> → {{val|1.23|exp=6|u=m/s|nocategory=true}}
*<code><nowiki>{{val|1.23|us=kbit/s}}</nowiki></code> → {{val|1.23|us=kbit/s|nocategory=true}}
*<code><nowiki>{{val|1.23|.05|.04|.03|u=m/s}}</nowiki></code> → {{val|1.23|.05|.04|.03|u=m/s|nocategory=true}}


== Format of numbers ==
== Format of numbers ==


{{tl|Val}} produces formatting compliant with Wikipedia's [[WP:MOSNUM|Manual of Style]].  
{{tl|Val}} produces formatting compliant with Wikipedia's [[WP:MOSNUM|Manual of Style]].


The [[Wikipedia:MOSNUM#Delimiting_(grouping_of_digits)|MOS]] recommends that numbers either be delimited using thin spaces either side of the decimal, or commas to the left and no delimiters to the right.  Articles should be consistent wrt the style of delimiting.  The template defaults to the former style, this can be adjusted using <code>|fmt=</code> (see [[#Arguments|above]]).
The [[Wikipedia:MOSNUM#Delimiting (grouping of digits)|MOS]] recommends that numbers either be delimited using thin spaces either side of the decimal, or commas to the left and no delimiters to the right.  Articles should be consistent with respect to the style of delimiting.  The template defaults to the former style, this can be adjusted using <code>|fmt=</code> (see [[#Arguments|above]]).


== Sorting ==
== Sorting ==
A hidden sort key is added to the output for sorting in sortable tables.  The sort key is based on the main value (parameter {{para|1}}) and, if used, the exponent for the power of 10 (parameter {{para|e}}) and/or units (parameters {{para|u}}, {{para|ul}}, {{para|up}} and/or {{para|upl}}).  Where necessary, units are converted to base SI units for the purpose of the sort key, which is produced by {{tl|ntsh}}.  Several units are covered [[#How to add units]] for those which are not. To omit the sort key use {{para|sortable|off}}.
{{details|Help:Sorting}}
 
The sort key for each sortable unit is visible at [[Template:Val/list]].


== Examples ==
Here is a live example showing the minimal markup for a sortable table:


:{|
{|
|style="vertical-align:top;" |
<pre>
{| class="sortable"
! Val sort test
! In base unit
|-
|-
|<code><nowiki>{{val|1234567890}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1234567890}}
| {{val|3|ul=  Mm }}
| {{val|3000000|u=m}}
|-
|-
|<code><nowiki>{{val|1.23456789}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.23456789}}
| {{val|4e6|ul= m }}
| {{val|4000000|u=m}}
|-
|-
|<code><nowiki>{{val|1.2345678}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.2345678}}
| {{val|1|ul=  km }}
| {{val|1000|u=m}}
|-
|-
|{{xpdop3c|gives={{!}}{{!}}&nbsp;→&nbsp;{{!}}{{!}}|d=|val|21563.252564425}}
| {{val|5e3|u= m }}
| {{val|5000|u=m}}
|-
|-
|colspan=3|'''Uncertainty/significance'''
| {{val|2|u=   m }}
| {{val|2|u=m}}
|}
</pre>
| style="vertical-align:top;" |<!--
-->
{| class="wikitable sortable floatright" summary="Val sorting test"
|+ Click to sort &darr;
|-
|-
|<code><nowiki>{{val|1.234|0.005}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|0.005}}
! Val sort test
! In base unit
|-
|-
|<code><nowiki>{{val|1.234|+0.005|-0.006}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|+0.005|-0.006}}
| {{val|3|ul=  Mm }}
| style="text-align:right" | {{val|3000000|u=m}}
|-
|-
|<code><nowiki>{{val|1.234|(5)}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|(5)}}
| {{val|4e6|ul= m }}
| style="text-align:right" | {{val|4000000|u=m}}
|-
|-
|colspan=3|'''Units'''
| {{val|1|ul=  km }}
| style="text-align:right" | {{val|1000|u=m}}
|-
|-
|<code><nowiki>{{val|1.234|u=m}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|u=m}}
| {{val|5e3|u= m }}
| style="text-align:right" | {{val|5000|u=m}}
|-
|-
|<code><nowiki>{{val|1.234|u=m2}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|u=m2}}
| {{val|2|u=   m }}
|-
| style="text-align:right" | {{val|2|u=m}}
|<code><nowiki>{{val|1.234|ul=m}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|ul=m}}
|}
|-
|<code><nowiki>{{val|123.4|ul=USgal}}</nowiki></code>||&nbsp;→&nbsp;||{{val|123.4|ul=USgal}}
|-
|<code><nowiki>{{val|12.34|ul=mpgimp}}</nowiki></code>||&nbsp;→&nbsp;||{{val|12.34|ul=mpgimp}}
|-
|<code><nowiki>{{val|12.34|u=deg}}</nowiki></code>||&nbsp;→&nbsp;||{{val|12.34|u=deg}}
|-
|<code><nowiki>{{val|1.234|0.005|u='}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|0.005|u='}}
|-
|<code><nowiki>{{val|1.234|+0.005|-0.006|u="}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|+0.005|-0.006|u="}}
|-
|colspan=3|'''Exponents'''
|-
|<code><nowiki>{{val|1.234|e=5|ul=m}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|e=5|ul=m}}
|-
|<code><nowiki>{{val|1.234|0.056|e=7}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|0.056|e=7}}
|-
|<code><nowiki>{{val|1.23456|+0.00007|-0.00008|e=-9|ul=m/s}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.23456|+0.00007|-0.00008|e=-9|ul=m/s}}
|-
|<code><nowiki>{{val|1.234|0.056|e=7|ul=psi}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|0.056|e=7|ul=psi}}
|-
|<code><nowiki>{{val|1.234|(5)|e=-2}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|(5)|e=-2}}
|-
|colspan=3|'''Prefix/suffix'''
|-
|<code><nowiki>{{val|p=Δ&amp;nbsp;|12.34}}</nowiki></code>||&nbsp;→&nbsp;||{{val|p=Δ&nbsp;|12.34}}
|-
|<code><nowiki>{{val|p=+|12.34|u=%}}</nowiki></code>||&nbsp;→&nbsp;||{{val|p=+|12.34|u=%}}
|-
|<code><nowiki>{{val|12.34|0.25|s=%}}</nowiki></code>||&nbsp;→&nbsp;||{{val|12.34|0.25|s=%}}
|-
|colspan=3|'''Numerator/Denominator'''
|-
|<code><nowiki>{{val|1.234|e=7|ul=W|up=m2}}</nowiki></code>||&nbsp;→&nbsp;||{{val|1.234|e=7|ul=W|up=m2}}
|}
|}


:'''More examples'''<br/>See the testcases at [[Template:Val/testcases|Val/testcases]].
A sort value relates to a Val expression as follows.
# The numeric value is a starting point.
# If the unit has an SI Prefix, that order of magnitude is applied.
# The value of the unit from its own [[system of units]] is applied.
# If the unit is composite, each subunit is multiplied or divided per their [[Dimensional analysis#Definition|dimension]].
# The result is passed to {{tl|ntsh}} which applies a normalization formula.
# The output of {{tlf|ntsh}} is added (behaviorally only, i.e. "hidden") into the table as usual, via the data-sort-value attribute of a table.


== Performance impact ==
== More example expressions ==


For most uses, in the text of articles, Template:Val will not restrict performance, but when used inside the wikitext markup of large templates, there are some restrictions. When displaying integer amounts, Template:Val has an internal [[m:HELP:Expansion depth|expansion depth]] of 15 levels, but for numbers with decimal portions, it uses 22 levels, or more.
=== Number ===
{{#invoke:DemoTemplate|val|1234567.1234567}}<br />
<code>.{<nowiki/>{val|{{spaces|2}}1234567.1234567{{spaces|3}}}}.</code> &rarr; .{{val| 1234567.1234567 }}.<br />
{{#invoke:DemoTemplate|val|fmt=commas|.1234567}}<br />
{{#invoke:DemoTemplate|val|fmt=commas|+1234567}}<br />
{{#invoke:DemoTemplate|val|-1234567}}<br />


== How to add units ==
===Uncertainty===
{{#invoke:DemoTemplate|val|1.234|0.005}}<br >
{{#invoke:DemoTemplate|val|1.234|0.005|e=3}}<br >
{{#invoke:DemoTemplate|val|1.234|+0.005|-0.006}}<br >
{{#invoke:DemoTemplate|val|1.234|(5)}}<br >


The unit you will add is required to have a link version and a non-link version for stylistic reasons (including the ability of editors to avoid [[WP:OVERLINKING|overlinking]]). The link version will be added to '''''Val/unitswithlink''''' to process the <code>ul</code> and <code>upl</code> [[m:Templates#Parameters|parameter]]s. The non-link version ''might'' need to be added to '''''Val/units''''' to process the <code>u</code> and <code>up</code> parameter; it depends on whether or not the unit needs [[Help:Wiki markup#Format|markup]], or if the characters users will give to the <code>ul</code> or <code>u</code> parameter are different than what is displayed, or if "technical reasons" are discovered. (See below.)
===Units===
{{#invoke:DemoTemplate|val|1.234|u=m}}<br >
{{#invoke:DemoTemplate|val|1.234|u=m2}}<br >
{{#invoke:DemoTemplate|val|1.234|ul=m}}<br >
{{#invoke:DemoTemplate|val|123.4|ul=USgal}}<br >
{{#invoke:DemoTemplate|val|12.34|ul=mpgimp}}<br >


Note these points before adding units:
{{#invoke:DemoTemplate|val|12.34|u=deg}}<br >
* For composite units you should probably link the whole, not individual units. For example the line you add would say <code> {{nowrap|{{xt|<nowiki>|m·s-1=[[Velocity|m·s{{sup|&minus;1}}]]</nowiki>}}}}</code> linking to ''Velocity'', not {{nowrap|<code>{{!xt|<nowiki>|m*s-1=[[Metre|m]]·[[Second|s]]{{sup|&minus;1}}</nowiki>}}</code>}}.  ''[[List of common physics notations]]'' has many examples of composite units that have their own page.
{{#invoke:DemoTemplate|val|1.234|0.005|u='}}<br >
* The val user can compose their own divisor unit from an existing unit, writing {{nowrap|<code><nowiki>{{val|ul=m|upl=s}}</nowiki></code>}} to render their own "{{val|ul=m|upl=s}}" with two links:  <code>m</code> to ''Meter'' and <code>s</code> to ''Second''. 
{{#invoke:DemoTemplate|val|1.234|+0.005|-0.006|u="}}<br >
* The val user can compose their own multiplier units by using the <code>end</code> parameter to prepend a string. For example, to prepend "{{val|ul=Ma}}", they could write {{nowrap|<code><nowiki>{{val|333|end=&amp;nbsp;Ma|ul=uBP}}</nowiki></code>}}, rendering "{{val|333|end=&nbsp;Ma|ul=uBP}}". These cannot be linked.


The technique involves activating "[[WP:Show changes|Show changes]]" to catch unintended changes that are otherwise difficult to detect in any of the many pages using val that would be affected.
{{#invoke:DemoTemplate|val|1.234|u=%}}<br >
# Edit {{tl|Val/unitswithlink/test}}.  The [[Sides of an equation|LHS]] of the "=" sign is what val users will give to the <code>ul</code> (or <code>upl</code>) parameter. Activate "[[WP:Show preview|Show preview]]".  This will run your test data through val, which would be similar to running val itself in a sandbox. [[Wikipedia:TESTLINK|Prove the intended link]] and markup here because you will not be able to show a preview in the next steps. [[Cut and paste|Copy]] what you will be adding to the wiki with the next steps. Save the page to serve as a "current list".
{{#invoke:DemoTemplate|val|1.234|end=&nbsp;[[m/s]]}}<br >
# Edit {{tl|Val/unitswithlink}}.  Paste the identical line proven in step 1.  Sort order is not important. Show changes, and then save.
# If the unit will display differently from what is typed into <code>u=</code>, edit {{tl|Val/units}}. Paste the identical line, and remove any [[help:wikilinks|links]] from the RHS of the "=" sign, being careful to leave any rendering work. Show changes, and then save.
# '''Important'''. Run <code><nowiki>{{Val|u=}}</nowiki></code> and <code><nowiki>{{Val|ul=}}</nowiki></code> in a [[WP:sand|sandbox]] and verify that your unit has an identical appearance in both cases. Edit {{tl|Val/units}} to make any corrections. (The discrepancy occurred for technical reasons.)
The last step is an important to the [[WP:MOSNUM|manual of style for dates and numbers]].


Units which are not sorting correctly may have to be added to {{tl|val/sortkey/unit}}. Add the unit code and the conversion factor to the SI base unit for the appropriate physical dimension.
{{#invoke:DemoTemplate|val|12.34|u=degC}}<br >
{{#invoke:DemoTemplate|val|12.34|u=K}}<br >


== FAQ and comments ==
===Exponents===
{{#invoke:DemoTemplate|val|1.234e5|ul=m}}<br >
{{#invoke:DemoTemplate|val|1.234|e=5|ul=m}}
 
{{#invoke:DemoTemplate|val|1.234e7|0.056}}<br >
{{#invoke:DemoTemplate|val|1.234|0.056|e=7}}
 
{{#invoke:DemoTemplate|val|1.23456e-9|+0.00007|-0.00008|ul=m/s}}<br >
{{#invoke:DemoTemplate|val|1.23456|+0.00007|-0.00008|e=-9|ul=m/s}}
 
{{#invoke:DemoTemplate|val|1.234e7|0.056|ul=psi}}<br >
{{#invoke:DemoTemplate|val|1.234|0.056|e=7|ul=psi}}


* '''Q: Why should I use val?'''
{{#invoke:DemoTemplate|val|1.234e-2|(5)}}<br />
: A1: {{tl|Val}} formats numbers:
{{#invoke:DemoTemplate|val|1.234|(5)|e=-2}}
:*inserts spaces between groups of digits, approximating SI standards
:*properly formats [[Uncertainty#Measurements|uncertainties in measurements]] and [[significant digits]], providing a ± character, etc.
:*properly formats [[Exponentiation|exponents of 10]] and [[scientific notation]]
:*replaces "-" (hyphen) with a "&minus;"  (minus sign)
: A2: It preserves spacing:
:* It makes sure the value does not [[Word wrap|wrap]] at the end of a line, so that it can always be read as a single value on one line in the text.
:* It spaces the various parts of the value where they should be
: A3: It automates the markup for, and a link to a displayed unit.
: A4: Val helps make Wikipedia more consistent. It adheres to the [[Wikipedia:MOSNUM|Wikipedia Manual of Style for numbers]]. Updates to the [[Wikipedia:MOSNUM|Wikipedia Manual of Style for numbers]] can be applied to this template, and result in automatic modification on values that use it. All this makes sure all values on all pages have the same [[look and feel]] because they will all use the same [[Letter-spacing|spacing]], [[font|font size]], positioning, etc, and makes updating and checking by the bots easier because they can recognize a value for what it is.


* '''Q: Why not use <nowiki><math></nowiki>?'''
===Prefix/suffix===
: A: For the same reasons [[Help:Math#Pros_of_HTML|HTML might be preferred over {{TeX}}]]:
{{#invoke:DemoTemplate|val|p=Δ&nbsp;|12.34}}<br >
:* Because the [[font]] in math tags differs both in face and size from the prose, which can disturb the layout of a page when used inline with the prose.
{{#invoke:DemoTemplate|val|p=≅|12.34|u=%}}<br >
:*You cannot [[cut and paste]] a bitmap image rendered by the Latex.
{{#invoke:DemoTemplate|val|12.34|0.25|s=%}}<br />
:*Images are slower to load and use more bandwidth, which is especially bad for the mobile version of Wikipedia.
:* <nowiki><math></nowiki> does not automatically adhere to the [[Wikipedia:MOSNUM|Wikipedia Manual of Style for numbers]].


* '''Q: Are there any known issues with val?'''
===Numerator/denominator===
: A1: Because numbers can only be stored with a limited precision by Wikipedia servers, val cannot handle very large numbers, such as 123456789123456789. This is reported using a {{tl|FormattingError}}, so it should be easy to spot. Because there is very limited use for such large numbers, there is no fix planned for this.
{{#invoke:DemoTemplate|val|1.234|e=7|ul=W|up=m2}}<br />
: A2: This template has been in full use on many pages for quite some time without major problems or [[wiktionary:breaking change|breaking changes]]. Technically, there is no good reason ''not'' to try val.


* '''Q: How should I use val?'''
===Repeating digits===
: A1: Val probably already has your unit on [[Template:Val/unitswithlink/test|its current list]]. If not, then your unit [[#How_to_add_units|can be added]].
<code><nowiki>{{val|1.2|end={{overline|34}}|e=7|ul=W|up=m2}}</nowiki></code> → {{val|1.2|end={{overline|34}}|e=7|ul=W|up=m2}}
: A2: To avoid [[WP:OVERLINKING|over linking]] switch from the ''ul='' to the ''u='' parameter of the given unit.


== See also ==
===Even more examples===
* <nowiki>{{val}}</nowiki> subtemplates:
See the testcases at {{tl|val/testcases}}.
*: {{tl|val/delimitnum}}, for formatting a decimal number with delimiters between groups of digits.
*: {{tl|val/units}}, for formatting unit names (contents of parameters<code>u</code>or<code>up</code>).
*: {{tl|val/unitswithlink}}, for formatting unit names with links (contents of parameters<code>ul</code>or<code>upl</code>).
* {{tl|formatting error}}, for reporting inconsistent parameters.
* {{tl|valid}}, for checking number validity (parameters 1, 2, 3, e : value, and uncertainties, base-10 exponent).


== FAQ and comments ==


{{Sup and sub-related templates}}
; Q. Why should I use Val?
{{Math templates|notation}}
: A1. Val formats numbers:
:*inserts spaces between groups of digits, meeting [[MOS:NUM|MoS standards]],
:*formats standard [[Uncertainty#Measurements|uncertainties in measurements]], providing a ± character, correct spacing, and correct alignment,
:*formats [[Exponentiation|exponents of 10]] and [[scientific notation]],
:*replaces "-" (hyphen) with a "&minus;" (minus sign).
: A2. Val preserves spacing:
:* It makes sure the value does not [[Word wrap|wrap]] at the end of a line, so that it can always be read as a single value on one line in the text.
:* It spaces the various parts of the value where they should be.
: A3. Configuring Val gives you your own code for automating the markup for, and a link to, any units in the entire Encyclopedia.
: A4. Val helps make Wikipedia more consistent. It adheres to the [[Wikipedia:MOSNUM|Wikipedia Manual of Style for numbers]]. Updates to the MoS can be applied to this template and result in automatic modification on values that use it. All this makes sure all values on all pages have the same [[look and feel]] because they will all use the same [[Letter-spacing|spacing]], [[font|font size]], positioning, etc, and makes updating and checking by the bots easier because they can recognize a value for what it is.
; Q. Why not use <nowiki><math></nowiki>?
: A. For the same reasons [[Help:Math#Pros of HTML|HTML might be preferred over TeX]]:
:*Because the [[font]] in math tags differs both in face and size from the prose, which can disturb the layout of a page when used inline with the prose.
:*You cannot [[Cut, copy, and paste|cut and paste]] a bitmap image rendered by the LaTeX.
:*Images are slower to load and use more bandwidth, which is especially bad for the mobile version of Wikipedia.
:*<nowiki><math></nowiki> does not automatically easily align to the Manual of Style for numbers.
; Q. Are there any known issues with Val?
: A1: This template is now a new Lua module as of Aug 6, 2015. Technically, there is no good reason not to try Val.
: A2. Issues are solved rapidly by an active set of responsive template coders.  See the talk page.
; Q. How should I use Val?
: A1. Val probably already has your unit on [[Module:Val/units|its current list]]. If not, add your own unit there.
: A2. To avoid [[WP:OVERLINKING|overlinking]], switch from {{para|ul}} to {{para|u}} and from {{para|upl}} to {{para|up}}.
: A3. Any time you have a unit to link or a table to sort, Val already setup with that unit's link and sorting value.
: A3. Use Val along with {{tl|Convert}}.  See [[Module:Convert/data|how to add units to Convert]].
: A4. Where consistent styling of long list articles, with many hundreds or thousands of numbers or units is needed.


== See also ==
* [[Module:Val]]
* [[Module:Val/units]]
* [[Module:Convert/data]]
* [[Template:Gaps]]
* [[Template:Decimals]]
* [[Template:Rnd]]
* [[Template:Scinote]] to display a value in scientific notation
* [[Template:10^]] to display a power of ten
<includeonly>{{basepage subpage| <!-- Categories below this line, please: -->
<includeonly>{{basepage subpage| <!-- Categories below this line, please: -->
[[Category:Mathematical formatting templates]]
[[Category:Mathematical formatting templates]]
Line 202: Line 308:
[[Category:Sorting templates]]
[[Category:Sorting templates]]
}}</includeonly>
}}</includeonly>
== TemplateData ==
{{TemplateData header}}
<templatedata>
{
"params": {
"1": {
"label": "Number",
"description": "A number in decimal point notation or in e notation. The main basis of the Val expression.",
"example": "-12.12345e9",
"type": "string",
"required": true
},
"2": {
"label": "Uncertainty",
"type": "string"
},
"3": {
"label": "Asymmetric uncertainty -",
"type": "string"
},
"4": {},
"5": {},
"fmt": {
"label": "Format",
"description": "By default, numbers are formatted with gaps separating groups of three digits in both integer and fractional part. However, by default, four-digit integers are not formatted; use \"gaps\" (without quotes) to force gaps. Use the value \"commas\" (without quotes) to delimit the integer part of the number with commas. Use \"none\" (without quotes) for no formatting (no gaps or commas).",
"example": "commas",
"type": "string"
},
"end": {
"label": "End",
"description": "Put something at the end of the main number (before anything else that might follow).",
"type": "string"
},
"u": {
"label": "Unit",
"description": "The unit code. A space and the unit will be added after the number.",
"example": "m",
"type": "string"
},
"ul": {
"label": "Unit – wikilinked",
"description": "The unit code that will be wikilinked to a page with information about the unit. A space and this unit will be added after the number.",
"example": "m",
"type": "string"
},
"up": {
"label": "Unit to be prefixed with a slash (/)",
"description": "A unit code, but instead of a space, the template adds a slash and the unit, a \"per\" unit (the denominator), to form a ratio.",
"example": "s",
"type": "string"
},
"upl": {
"label": "Unit to be prefixed with a slash (/) – wikilinked",
"description": "A wikilinked unit code, but instead of a space, the template adds a slash and the unit, a \"per\" unit (the denominator), to form a ratio.",
"example": "s",
"type": "string"
},
"p": {
"label": "Prefix",
"description": "Prefix for the entire Val expression. Non-spaced, but accepts markup.",
"type": "content"
},
"s": {
"label": "Suffix",
"description": "Suffix for the entire Val expression. Non-spaced, but accepts markup.",
"type": "content"
},
"e": {
"label": "Exponent",
"description": "Val alternatively accepts e notation in the first parameter; these are mutually exclusive (see the Number parameter).",
"example": "9",
"type": "number"
},
"errend": {}
},
"paramOrder": [
"1",
"2",
"3",
"fmt",
"end",
"u",
"ul",
"up",
"upl",
"p",
"s",
"e",
"errend",
"4",
"5"
],
"format": "inline",
"description": "This template is used to easily present values in scientific notation, including uncertainty and/or units, as prescribed by Wikipedia's Manual of Style."
}
</templatedata>

Latest revision as of 14:08, 3 September 2020

This template is used to easily present values in scientific notation, including uncertainty and/or units, as prescribed by Wikipedia's Manual of Style.

Introduction

Val specializes in numeric values, especially those with scientific notations, uncertainty notations, and those with measurement values with physical units. Because these expressions are covered by the Manual of Style, Val provides the stylized output for you, and keeps them from wrapping across lines.

Express a numeral:

  • {{val|123456.78901}}value, formatted with gaps: 123456.78901, or with |fmt=commas123,456.78901
  • {{val|number|number}}value ± uncertainty, like 123,478±56
  • {{val|number|(number)}}value(uncertainty), like 12,345(56)
  • {{val|number|number|number}}value +uncertainty
    −uncertainty
    like 1234+56
    −78

Express a measurement value: {{val|4|ul=m2}}m2. The m2 is a "unit code" that Val uses to lookup the link to the unit's article, and the formatting of the unit symbol. Val links the units to the page it has on file for them. See {{Val/list}}.

There are a large number of unit codes that Val understands and keeps "up to code". A unit code is the just abbreviated unit name, but these can get quite involved for a compound or composite unit, with "multipliers" or "dividers". See Module:Val/units.

Some unit-code flexibility is provided by having four parameters to work the unit-code system: whether to link one or not, (see Overlinking), and whether to link the numerator or denominator of a unit ratio separately.

  • {{val|number|ul=unit code}}number symbol, such as 9.8 km2
  • {{val|number|u=unit code}}number symbol, such as 9.8 km2
  • {{val|number|u=unit code|upl=unit code}}number symbol/symbol, such as 9.8 gal/min
  • {{val|number|ul=unit code|up=unit code}}number symbol/symbol, such as 9.8 pc/year

To bypass the unit code system, if |u= does not recognize your unit code, it will accept any wikitext and render it as usual.

  • {{val|5.4|u=[[kg]]&sdot;[[meter|m]]/s<sup>2</sup>}}5.4 kgm/s2
  • {{val|7.6|u=[[metre per second squared|m/s<sup>2</sup>]]}}7.6 m/s2

See Module:Val/units for how to add units to the unit code system.

Sometimes a number and unit code is not enough. A prefix or suffix are also available, |p= and |s=.

  • {{val|7600|p=>|s=<|u=C&sdot;Ga}}>7600 C⋅Ga<
  • {{val|7600|p=<span style="color:green"><sup>|s=</sup></span>|u=C}}7600 C

See {{val/testcases}} to learn the val parameters by an example. It is comprehensive, and there are over 100 examples.

Arguments

Val takes three unnamed parameters. The first is always the numeric value. When the second and third are numbers they become the various uncertainty notations, but the second unnamed parameter can also serve to grammatically join the first and third numbers.

Val clears surrounding spaces in its unnamed parameters.

1st or |1= A number in decimal point notation or in e notation. The main basis of the Val expression.

{{val|1234567.1234567}}1234567.1234567
{{val|.1234}}0.1234                    (adds the zero)
{{val|+1234}}+1234                     (displays the plus)
{{val|-1234}}−1234                     (replaces the hyphen-minus with a minus sign)
{{val|12e34}}12×1034                (E notation)

|fmt= By default, numbers are formatted with gaps separating groups of three digits in both integer and fractional part.

However, by default, four-digit integers are not formatted; use |fmt=gaps to force gaps.
Use |fmt=commas to delimit the integer part of the number with commas.
Use |fmt=none for no formatting (no gaps or commas).
{{val|1234567.1234567}}1234567.1234567
{{val|1234567.1234567|fmt=commas}}1,234,567.1234567
{{val|1234}}1234
{{val|1234|fmt=gaps}}1234
{{val|1234.5}}1234.5
{{val|1234.5|fmt=none}}1234.5

|end= Put something at the end of the main number (before anything else that might follow).

{{val|11|end=<END>}}11<END>
{{val|11|22|end=<END>}}11<END>±22
{{val|1111|(22)|end=<END>}}1111<END>(22)
{{val|11|22|33|end=<END>}}11<END>+22
−33

{{val|11|ul=m/s|end=<END>}}11<END> m/s

2nd or |2= Uncertainty in either format.

{{val|11|22}}11±22
{{Val|11|(22)}}11(22)
A conjunction to join two numbers. Useful for ranges, grammatical output, etc.
{{val|11|-|33}}11–33
{{val|11|–|33}}11–33
{{val|11|,|33}}11, 33
{{val|11|by|33|e=9}}(11 by 33)×109
{{val|11|and|33|end=$}}11$ and 33$
{{val|11|or|33}}11 or 33
{{val|11|to|33}}11 to 33
{{val|11|x|33}}11 × 33
{{val|11|×|33}}11 × 33
{{val|11|/|33|ul=m/s}}11/33 m/s
Note that for dashes or x's, the various kinds all obtain one properly styled output.

3rd or |3= Asymmetric uncertainty.

{{Val|11|22|33}}11+22
−33

|errend= or |+errend= and |-errend= Appends something after an uncertainty.

{{val|11|22|errend=<Errend>}}11±22<Errend>
{{val|11|22|33|-errend=<−Errend>|+errend=<+Errend>}}11+22<+Errend>
−33<−Errend>

|u= or |ul= The unit code. Val adds a space and the unit.

|ul= Link the unit.
|u= Don't link the unit. Also accepts wiki markup in lieu of a unit code.
{{val|11|ul=m}}11 m

|up= or |upl= A unit code, but instead of a space Val adds a slash and the unit, a "per" unit (the denominator), to form a ratio.

|upl= Link the per unit.
|up= Don't link the per unit.
The ratio can be of two unit codes, or a prefix and a unit code. Val will add parentheses to disambiguate, if a unit code has a dot or a slash.
{{Val|11|ul=J/C|upl=F/m}}11 (J/C)/(F/m)
{{Val|11|p=$|upl=acre}}$11/acre
{{Val|11|ul=km/s|upl=Mpc}}11 (km/s)/Mpc
{{Val|11|ul=kg.m|upl=s-2}}11 (kg⋅m)/s−2

|p= Prefix the entire Val expression. Non-spaced, but accepts markup.

{{Val|11|22|ul=m/s|p=<Prefix>}}<Prefix>11±22 m/s
{{Val|11|22|ul=m/s|p=<Prefix>&nbsp;}}<Prefix> 11±22 m/s

|s= Suffix the entire Val expression. Non-spaced, but accepts markup.

{{Val|11|22|ul=m/s|s=<Suffix>}}11±22 m/s<Suffix>
{{Val|11|22|ul=m/s|s=&nbsp;<Suffix>}}11±22 m/s <Suffix>

|e= Exponent. Val alternatively accepts e notation in the first parameter; these are mutually exclusive (see "1st" argument above).

{{Val|11|22|33|e=11}}11+22
−33
×1011

{{Val|11e11|22|33}}11+22
−33
×1011

|long scale= Usually a unit is the short ton and billion means 1×109. But there are long versions of these units and others. Use |long scale=on to assign your unit to the long scale instead. The unit code's link will change and it will sort differently in tables. "See Long and short scales".
|nocategory= If set to any value, errors in the use of this template will not cause the page to be added to the Pages with incorrect formatting templates use category. This is useful for documentation and test pages that do not need to be fixed.

Errors

There is strict checking on the validity of arguments; any incorrect use will result in an error, which is displayed using {{FormattingError}}. Pages that contain incorrect use of this template will show up on Category:Pages with incorrect formatting templates use.

Val checks for unsupported parameters and gives a relatively subtle warning if found. See tracking category to track any of these improper usages on existing on the wiki. Hold the mouse over "warning" to see details. Here is what warnings look like:

  • {{val|1.23|exp=6|u=m/s}}1.23 m/sError in {{val}}: Val parameter "exp=6" is not supported
  • {{val|1.23|us=kbit/s}}1.23Error in {{val}}: Val parameter "us=kbit/s" is not supported
  • {{val|1.23|.05|.04|.03|u=m/s}}1.23+0.05
    −0.04
     m/s
    Error in {{val}}: Val parameter 4 ignored

Format of numbers

{{Val}} produces formatting compliant with Wikipedia's Manual of Style.

The MOS recommends that numbers either be delimited using thin spaces either side of the decimal, or commas to the left and no delimiters to the right. Articles should be consistent with respect to the style of delimiting. The template defaults to the former style, this can be adjusted using |fmt= (see above).

Sorting

The sort key for each sortable unit is visible at Template:Val/list.

Here is a live example showing the minimal markup for a sortable table:

{| class="sortable"
! Val sort test
! In base unit
|-
| {{val|3|ul=  Mm }}
| {{val|3000000|u=m}}
|-
| {{val|4e6|ul= m }}
| {{val|4000000|u=m}}
|-
| {{val|1|ul=  km }}
| {{val|1000|u=m}}
|-
| {{val|5e3|u=  m }}
| {{val|5000|u=m}}
|-
| {{val|2|u=    m }}
| {{val|2|u=m}}
|}
Click to sort ↓
Val sort test In base unit
Mm 3000000 m
4×106 m 4000000 m
km 1000 m
5×103 m 5000 m
2 m 2 m

A sort value relates to a Val expression as follows.

  1. The numeric value is a starting point.
  2. If the unit has an SI Prefix, that order of magnitude is applied.
  3. The value of the unit from its own system of units is applied.
  4. If the unit is composite, each subunit is multiplied or divided per their dimension.
  5. The result is passed to {{ntsh}} which applies a normalization formula.
  6. The output of {{ntsh}} is added (behaviorally only, i.e. "hidden") into the table as usual, via the data-sort-value attribute of a table.

More example expressions

Number

{{val|1234567.1234567}}1234567.1234567
.{{val|  1234567.1234567   }}. → .1234567.1234567.
{{val|.1234567|fmt=commas}}0.1234567
{{val|+1234567|fmt=commas}}+1,234,567
{{val|-1234567}}−1234567

Uncertainty

{{val|1.234|0.005}}1.234±0.005
{{val|1.234|0.005|e=3}}(1.234±0.005)×103
{{val|1.234|+0.005|-0.006}}1.234+0.005
−0.006

{{val|1.234|(5)}}1.234(5)

Units

{{val|1.234|u=m}}1.234 m
{{val|1.234|u=m2}}1.234 m2
{{val|1.234|ul=m}}1.234 m
{{val|123.4|ul=USgal}}123.4 US gal
{{val|12.34|ul=mpgimp}}12.34 mpgimp

{{val|12.34|u=deg}}12.34°
{{val|1.234|0.005|u='}}1.234′±0.005′
{{val|1.234|+0.005|-0.006|u="}}1.234″+0.005″
−0.006″

{{val|1.234|u=%}}1.234%
{{val|1.234|end=&nbsp;[[m/s]]}}1.234 m/s

{{val|12.34|u=degC}}12.34 °C
{{val|12.34|u=K}}12.34 K

Exponents

{{val|1.234e5|ul=m}}1.234×105 m
{{val|1.234|ul=m|e=5}}1.234×105 m

{{val|1.234e7|0.056}}(1.234±0.056)×107
{{val|1.234|0.056|e=7}}(1.234±0.056)×107

{{val|1.23456e-9|+0.00007|-0.00008|ul=m/s}}1.23456+0.00007
−0.00008
×10−9 m/s

{{val|1.23456|+0.00007|-0.00008|ul=m/s|e=-9}}1.23456+0.00007
−0.00008
×10−9 m/s

{{val|1.234e7|0.056|ul=psi}}(1.234±0.056)×107 psi
{{val|1.234|0.056|ul=psi|e=7}}(1.234±0.056)×107 psi

{{val|1.234e-2|(5)}}1.234(5)×10−2
{{val|1.234|(5)|e=-2}}1.234(5)×10−2

Prefix/suffix

{{val|12.34|p=Δ&nbsp;}}Δ 12.34
{{val|12.34|p=≅|u=%}}≅12.34%
{{val|12.34|0.25|s=%}}12.34±0.25%

Numerator/denominator

{{val|1.234|e=7|ul=W|up=m2}}1.234×107 W/m2

Repeating digits

{{val|1.2|end={{overline|34}}|e=7|ul=W|up=m2}}1.234×107 W/m2

Even more examples

See the testcases at {{val/testcases}}.

FAQ and comments

Q. Why should I use Val?
A1. Val formats numbers:
A2. Val preserves spacing:
  • It makes sure the value does not wrap at the end of a line, so that it can always be read as a single value on one line in the text.
  • It spaces the various parts of the value where they should be.
A3. Configuring Val gives you your own code for automating the markup for, and a link to, any units in the entire Encyclopedia.
A4. Val helps make Wikipedia more consistent. It adheres to the Wikipedia Manual of Style for numbers. Updates to the MoS can be applied to this template and result in automatic modification on values that use it. All this makes sure all values on all pages have the same look and feel because they will all use the same spacing, font size, positioning, etc, and makes updating and checking by the bots easier because they can recognize a value for what it is.
Q. Why not use <math>?
A. For the same reasons HTML might be preferred over TeX:
  • Because the font in math tags differs both in face and size from the prose, which can disturb the layout of a page when used inline with the prose.
  • You cannot cut and paste a bitmap image rendered by the LaTeX.
  • Images are slower to load and use more bandwidth, which is especially bad for the mobile version of Wikipedia.
  • <math> does not automatically easily align to the Manual of Style for numbers.
Q. Are there any known issues with Val?
A1: This template is now a new Lua module as of Aug 6, 2015. Technically, there is no good reason not to try Val.
A2. Issues are solved rapidly by an active set of responsive template coders. See the talk page.
Q. How should I use Val?
A1. Val probably already has your unit on its current list. If not, add your own unit there.
A2. To avoid overlinking, switch from |ul= to |u= and from |upl= to |up=.
A3. Any time you have a unit to link or a table to sort, Val already setup with that unit's link and sorting value.
A3. Use Val along with {{Convert}}. See how to add units to Convert.
A4. Where consistent styling of long list articles, with many hundreds or thousands of numbers or units is needed.

See also


TemplateData

This is the TemplateData for this template used by TemplateWizard, VisualEditor and other tools. See a monthly parameter usage report for this template in articles based on this TemplateData.

TemplateData for Val

This template is used to easily present values in scientific notation, including uncertainty and/or units, as prescribed by Wikipedia's Manual of Style.

Template parameters

This template prefers inline formatting of parameters.

ParameterDescriptionTypeStatus
Number1

A number in decimal point notation or in e notation. The main basis of the Val expression.

Example
-12.12345e9
Stringrequired
Uncertainty2

no description

Stringoptional
Asymmetric uncertainty -3

no description

Stringoptional
Formatfmt

By default, numbers are formatted with gaps separating groups of three digits in both integer and fractional part. However, by default, four-digit integers are not formatted; use "gaps" (without quotes) to force gaps. Use the value "commas" (without quotes) to delimit the integer part of the number with commas. Use "none" (without quotes) for no formatting (no gaps or commas).

Example
commas
Stringoptional
Endend

Put something at the end of the main number (before anything else that might follow).

Stringoptional
Unitu

The unit code. A space and the unit will be added after the number.

Example
m
Stringoptional
Unit – wikilinkedul

The unit code that will be wikilinked to a page with information about the unit. A space and this unit will be added after the number.

Example
m
Stringoptional
Unit to be prefixed with a slash (/)up

A unit code, but instead of a space, the template adds a slash and the unit, a "per" unit (the denominator), to form a ratio.

Example
s
Stringoptional
Unit to be prefixed with a slash (/) – wikilinkedupl

A wikilinked unit code, but instead of a space, the template adds a slash and the unit, a "per" unit (the denominator), to form a ratio.

Example
s
Stringoptional
Prefixp

Prefix for the entire Val expression. Non-spaced, but accepts markup.

Contentoptional
Suffixs

Suffix for the entire Val expression. Non-spaced, but accepts markup.

Contentoptional
Exponente

Val alternatively accepts e notation in the first parameter; these are mutually exclusive (see the Number parameter).

Example
9
Numberoptional
errenderrend

no description

Unknownoptional
44

no description

Unknownoptional
55

no description

Unknownoptional