Template:Val/doc

This template is used to easily present values in scientific notation, including uncertainty and/or units, as prescribed by Wikipedia's Manual of Style. It wraps the entire result in a {{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.)

Arguments

There are four ways this template can be used:

• {{val|number}} - for displaying values without uncertainty/significance.
• {{val|number|uncertainty}} - for displaying values with uncertainty, like so: 1234±56.
• {{val|number|upper uncertainty|lower uncertainty}} - for displaying values with uncertainty, like so: 1234+56
  −78.
• {{val|number|(significance)}} - for displaying values with significance, like so: 1234(56).

They all take roughly the same arguments

1	The value (must be a valid number)
2	The (upper limit of) uncertainty (must be a valid number) or significance (must be a valid number in parenthesis)
3	The lower limit of uncertainty (must be a valid negative number)
e	The exponent for the power of 10 (optional). This will show up in the result as: ×10e .
sortval	Alternative sorting factor to 1
u / ul	Activate units and any markup / with a link to a page about the unit (optional / optional)
up / upl	Construct units, and this is the "per" unit that is the denominator / with a link to a page about the denominator 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 {{val/unitswithlink}} or if they are supported by {{convert}}). You can specify units using just u; a good example is "ul=m/s", which gets translated to "m/s", or you can use u and up, as in "u/up"; a good example is "ul=m|up=s", which gets translated to "m/s".
us / ups	Alternative unit code for sorting.
p	A prefix for the value (such as ∆, ⌀, etc.; optional).
s	A suffix for the value (such as %, optional). 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.
end	Appends something after the main value. For example, {{val|123.24|end=...}} gives 123.24...
errend	Appends something after the uncertainty. For example, {{val|123.23|end=...|2.34|errend=...}} gives 123.23...±2.34...
+errend & -errend	Appends something after the positive/negative uncertainties. For example, {{val|123.23|end=...|+2.34|+errend=...|-1.23|-errend=...}} gives 123.23...+2.34... −1.23...
fmt	Allows alternative formatting using commas to the left of the decimal point as opposed gaps either side. For example, {{val|123123.123123|fmt=commas}} gives 123,123.123123
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.
long scale	Use |long scale=on to link and sort |u=billion etc. according to the "long scale".

See {{val/testcases}} to learn the commands. Learn by a example. Comprehensive. Over 100 examples. Edit a section there to learn what a "sandbox" is.

So Val's unit types are "unit" and "unit per", and each has the option for a link to their article: you say u for a unnit and up for a unit comprising the denominator portion of a compound unit. Use the argument names ending in L for the linked version, ul for a "unit link" (and upl for a "unit-per link", saying for example ul=kWh as an argument to Val. (Don't overlink. Use ul first, then mostly u afterwords.)

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.

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

A hidden sort key is added to the output for sorting in sortable tables. The sort key is based on the main value (parameter |1=) and, if used, the exponent for the power of 10 (parameter |e=) and/or units (parameters |u=, |ul=, |up= and/or |upl=). Where necessary, units are converted to base SI units for the purpose of the sort key, which is produced by {{ntsh}}. Several units are covered; see § How to add units for those which are not. To omit the sort key use |sortable=off.

Examples

{{val|1234567890}}	→	1234567890
{{val|1.23456789}}	→	1.23456789
{{val|1.2345678}}	→	1.2345678
Template:Xpdop3c
Uncertainty/significance
{{val|1.234|0.005}}	→	1.234±0.005
{{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 mpg‑imp
{{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″
Exponents
{{val|1.234|e=5|ul=m}}	→	1.234×105 m
{{val|1.234|0.056|e=7}}	→	(1.234±0.056)×107
{{val|1.23456|+0.00007|-0.00008|e=-9|ul=m/s}}	→	1.23456+0.00007 −0.00008×10−9 m/s
{{val|1.234|0.056|e=7|ul=psi}}	→	(1.234±0.056)×107 psi
{{val|1.234|(5)|e=-2}}	→	1.234(5)×10−2
Prefix/suffix
{{val|p=Δ |12.34}}	→	Δ 12.34
{{val|p=+|12.34|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

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

Performance impact

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 expansion depth of 15 levels, but for numbers with decimal portions, it uses 22 levels, or more.

How to add units

Add the unit to Template:Val/units. Val can lookup units at {{Convert}}, but the behavior of units added here override it.

Note these points about composite units before adding units:

• For composite units you should probably link the whole, not individual units. For example the line you add would say |m.s-1=[[Metre per second|m⋅s{{sup|−1}}]] linking to Metre per second, not |m.s-1=[[Metre|m]]⋅[[Second|s]]{{sup|−1}}. List of common physics notations has many examples of composite units that have their own page.
• The val user can compose their own divisor unit from an existing unit, for example writing {{val|99|ul=m|upl=s}} to render their own "99 m/s" with two links: m to Meter and s to Second.
• The val user can compose their own multiplier units by using the end parameter to prepend a string. For example, in a geology article, to prepend "Ma", to the unit in 333 ¹⁴C yr BP they could write {{val|333|end= Ma|ul=uBP}}, rendering "333 Ma ¹⁴C yr BP". (The end parameters cannot be linked.)

After adding a unit, you can guarantee it sorts in a table, especially if it has ten or twenty versions of itself that differ only by an SI prefix. (See the section about #Sorting, above. See {{Val/sortkey/unit}}.)

FAQ and comments

• Q: Why should I use Val?

A1: Val formats numbers:

• inserts spaces between groups of digits, approximating SI standards
• properly formats uncertainties in measurements and significant digits, providing a ± character, etc.
• properly formats exponents of 10 and scientific notation
• replaces "-" (hyphen) with a "−" (minus sign)

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 [[Help:Math#Pros_of_HTML|HTML might be preferred over Template: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: 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 {{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.

A2: This template has been in full use on many pages for quite some time without major problems or breaking changes. Technically, there is no good reason not to try Val.

A3: 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, then your unit can be added.

A2: To avoid over linking switch from the ul= to the u= parameter of the given unit.

A3: Use Val along with {{Convert}}. See how to add units to Convert.

See also

• {{Val}} subtemplates:

  {{Val/units}}, for the list of customized units, their markup, their link, and to configure your own codename for your own unit (whose name you choose goes into any of the named parameters with the letter u in there names).

  Similarly {{Val/angle}}, for the handling of unspaced units.

  {{val/delimitnum}}, for setting your own delimiters between groups of digits instead of using the default (spaces).

  {{Val/sortkey/unit}} for guaranteeing table sorting

• {{formatting error}}, to fix inconsistencies when the error you are given is not the error you find you have.