Template:Val/doc
This is a documentation subpage for Template:Val. It may contain usage information, categories and other content that is not part of the original template page. |
Purpose
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 ".
|
u / ul | Activate units and their formatting and spacing / 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 (requires numerator from u or ul)
|
p | A prefix for the value (such as ∆, ⌀, etc.; optional). |
s | A suffix for the value (such as %, optional).
|
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... |
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. |
See {{val/test}} for a list of examples of the correct output of {{val}} and the errors it may return when incorrectly used.
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 convention
As mentioned before, {{val}} should produce formatting compliant with Wikipedia's Manual of Style. It currently produces formatting compliant with the U.S. Government Printing Office Style Manual, in rules 12.9e and 12.14, which requires that the decimal separator be a full stop; i.e. “decimal point” (.), requires comma-delimiting to the left of the decimal point for numbers with four or more digits to the left (values of 1000 or more), and also requires space-delimiting to the right of the decimal point for numbers containing five or more digits to the right (e.g., 0.12345 and 5.12345 and 125.12345).
Note that if {{val}} is used on numbers simultaneously comprising four or more digits to the left of the decimal point and five or more digits to the right, the resultant expression will delimited with commas left and spaces (actually non-selectable, non-breaking, narrow gaps) right (see below).
Examples
{{val|1234567890}}
→ 1234567890 {{val|1.23456789}}
→ 1.23456789 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) Exponents/units {{val|1.234|e=5|u=m}}
→ 1.234×105 m {{val|1.234|e=5|u=m2}}
→ 1.234×105 m2 {{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|123.4|ul=USgal}}
→ 123.4 US gal {{val|12.34|ul=mpgimp}}
→ 12.34 mpg‑imp Prefix/suffix {{val|p=Δ |12.34|s=%}}
→ Δ 12.34% Numerator/Denominator {{val|1.234|e=7|ul=W|up=m2}}
→ 1.234×107 W/m2
- More examples
See the testcases at Val/test.
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
The unit is required to have a link version and a non-linked version for stylistic reasons (including the ability of editors to avoid overlinking). The linked version will be implemented by {{Val/unitswithlink}} (processing Val's "ul=" and "upl=" parameters). The non-linked version may or may not need to be implemented by {{Val/units}} (processing Val's "u=" and "up="parameter); it depends on whether or not the unit wants any special markup: if the characters given to the ul or u parameter are same as what is rendered, then you can skip the last step.
Before creating a complex unit with numerator and denominator, note that users can construct there own unit from existing simpler units, to achieve the formatting and spacing advantages val offers: {{val|3|e=7|ul=W|upl=m2}}, which renders 3×107 W/m2 uses the existing val unit "W" to link to Watt, and the existing val unit "m" to link to Meter. But for linking this "Watts per meter squared" to its meaning at Intensity (physics) using a single parameter, say Wm-2
(for u or ul), you may need to add the unit. (See List of common physics notations for other examples.)
The technique should involve activating Show changes in order to find-out any inadvertent changes.
- Edit {{Val/unitswithlink/test}}. The LHS of the "=" sign is what users will give to the ul (and upl) parameter. Preview. Because Val/unitswithlink/test data is process through Val/unitswithlink the preview is the same test as running val itself in a sandbox. Prove the intended markup and link for your newly added unit, show changes, and save the change.
- Edit {{Val/unitswithlink}}. Provide the wiki with the identical entry proven in step 1. Show changes. Save the change.
- Edit {{Val/units}}, but only if the unit required markup. The RHS of the "=" sign has no wikilinks, it has only markup, including using templates that supply the markup. Provide the proven unit, show changes, and save the change.
You can then verify a u and a ul instance of val, side by side in a sandbox. They should render the same characters for the unit, and one should supply a plain unit without the link.
Note that sorting and grouping of the data you are editing does not matter. The whole file becomes an instant blob of data for the template.
See also
- {{Valid}} : number validity checking (for parameters 1, 2, 3, e : value, and uncertainties, base-10 exponent)
- {{FormattingError}} : for reporting inconsistent parameters
- {{Val/delimitnum}} : for formatting a decimal number with delimiters between groups of digits
- {{Su}} : for formatting exponents, or two-values incertainty one below the other (monospaced : currently not printable to PDF)
- Template:T1 : for positive <sup> and negative <sub>
- {{Val/units}} : for formatting unit names (contents of parameters u or up)
- {{Val/unitswithlink}} : for formatting unit names with links (contents of parameters ul or upl)