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.)

Introduction

Val stands for "value" and is used for numeric values in the various scientific notations, and also used for measurement values with physical units. It formats these according to the Manual of Style and keeps them from wrapping across lines.

Express a numeral, with various notations for uncertainty:

• {{val|number}} → value, formated with gaps: 123456.789012 or commas: 123,456.789012.
• {{val|number|number}} → value ± uncertainty, like 12,345±56
• {{val|number|(number)}} → value(uncertainty), like 12,345(56).
• {{val|number|number|negative number}} →value ^+uncertainty
  _{−uncertainty} like 12,345+56
  −78

Express numerals with units, such as "4 m/s²", with a non-breaking space and markup and optional link. Now, because the markup for units is a standards issue and a style issue, Val provides easily type-able codes, called "unit codes" to provide the markup according to the Manual of Style. These codes are kept "up to code".

Providing four parameters for units offers complete flexibility within the unit-code system:

• {{val|number|u=unit code}} → number markup , such as 9.8 m/s²
• {{val|number|ul=unit code}} → number [[Article|markup]], such as 9.8 m/s²
• {{val|number|u=unit code|upl=unit code}} → number markup/[[Article|markup]], such as 9.8 m/s²
• {{val|number|ul=unit code|up=unit code}} → [[Article|markup]]/markup, such as 9.8 m/s²

There are thousands of unit codes, comprised of short, simple alphanumeric and slash characters, that Val understands, and are mostly intuitive. But you can also bypass the unit code system and supply your own markup and link. Just use |u=. Val will add the space and keep it from wrapping.

{{val|7.6|u=[[Foo|m{{su|b=8|}}⋅<math>3.4^{+0.3}_{-0.2}</math>s]]/[[Example|s<sup>4]]}} → 7.6 m
₈⋅<math>3.4^{+0.3}_{-0.2}</math>/s⁴

If |u= contains square bracket or angle bracket characters, it renders as any normal wikitext will. Normally all four of the parameters with u in them expect your unit code.

See below for a list of unit codes and how to easily add your own unit code to Val for use anywhere. There are also many more ways to package your numeral and its unit.

See {{val/testcases}} to learn the commands by a example. It's comprehensive, and there's over 100 examples. Edit a section there to learn what a "sandbox" is.

Arguments

1	The value. A number. (The usual decimal notation: possible decimal point, "-" sign, or "+" sign.)
2	A measure of uncertainty. A number that will get prefixed with ± if not given (and returned) in parentheses. Or the superscripted number +uncertainty for 3.
3	The subscripted number -uncertainty for 2.
e	The exponent for the power of 10 (optional). This will show up in the result as: ×10e .
fmt	Formatting. Accepts "commas". {{val|123456.123456|fmt=commas}} gives 123,456.123456
u or ul	The unit code. Val adds a non-breaking space and the unit. Use |ul= to provide the "unit with link" to the page about the unit. Do this on its first mention, but use |u= for later mentions so as not to overlink. See § How to add units below.
up and upl	The unit code. Val adds no spacing. Instead of a space Val adds a slash right in front of these "unit per" types of units. {{Val|120|p=$|upl=acre}} →$120/acre
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. {{val|1234|end=^}} gives 123.24^
errend	Appends something after the uncertainty. For example, {{val|1234|5678|errend=∞}} gives 1234±5678∞
+errend -errend	Appends something after the superscripted uncertainty. {{val|123|4|5|+errend=H|-errend=L}} gives 1+2H −3L
sortval	Alternative sorting factor to 1
us / ups	Alternative unit code for sorting.
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.

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 defaults to looking up units at {{Convert}}, but units added here override that.

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 ensure that it sorts correctly in a table, especially if there are ten or twenty variations that differ only by an SI prefix. (See § Sorting above and Template: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: 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.

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

A2: To avoid over linking switch from |ul= to |u= and from |upl= to |up=.

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.