'\" t
.\"     Title: rink-defs
.\"    Author: [see the "AUTHOR(S)" section]
.\" Generator: Asciidoctor 2.0.21
.\"      Date: 2024-05-01
.\"    Manual: Rink Manual
.\"    Source: Rink Manual
.\"  Language: English
.\"
.TH "RINK\-DEFS" "5" "2024-05-01" "Rink Manual" "Rink Manual"
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.ss \n[.ss] 0
.nh
.ad l
.de URL
\fI\\$2\fP <\\$1>\\$3
..
.als MTO URL
.if \n[.g] \{\
.  mso www.tmac
.  am URL
.    ad l
.  .
.  am MTO
.    ad l
.  .
.  LINKSTYLE blue R < >
.\}
.SH "NAME"
rink-defs \- Rink\*(Aqs `definition.units` format
.SH "DESCRIPTION"
.sp
The units database is a textual document containing the definitions of
units, prefixes, base units, quantities, and substances.
.sp
Comments start with \f(CR#\fP and continue to the end of the line. Blank lines
are ignored. Comments can be placed on the same line as units, at the
end.
.sp
.if n .RS 4
.nf
.fam C
 # This line is a comment
 # And so is this
.fam
.fi
.if n .RE
.SS "Units"
.sp
Units are defined with their name and their definition separated by
whitespace. A definition can be broken over multiple lines using \f(CR\(rs\fP if
desired.
.sp
.if n .RS 4
.nf
.fam C
foot                    12 inch
.fam
.fi
.if n .RE
.sp
Documentation comments are lines starting with \f(CR??\fP. They apply to the
next definition following them. They are shown to end users in Rink when
you query a definition.
.sp
.if n .RS 4
.nf
.fam C
?? International yard and pound, since July 1, 1959.
?? Documentation comments can be broken over
?? multiple lines.
foot                    12 inch
.fam
.fi
.if n .RE
.SS "Substances"
.sp
Substances can represent either a specific object (such as the Earth, or
the Sun), a material such as water or concrete, a chemical molecule, an
element of the periodic table, or an elementary particle.
.sp
A substance has a name, an optional symbol (used for chemical formulas),
and contains a list of properties inside of a {} block.
.sp
Properties can either be "const", which is mainly used for countable
objects such as a particle, or they can be a ratio, such as the density
of a material.
.sp
.if n .RS 4
.nf
.fam C
neutron {
    mass                const neutron_mass          1.00866491588 u
    wavelength          const neutron_wavelength    planck_constant / mass c
    magnetic_moment     const neutron_moment        \-0.96623650e\-26 J/T
}
.fam
.fi
.if n .RE
.sp
The two syntax variants for properties are:
.sp
.if n .RS 4
.nf
.fam C
 [name] const [output name] [expression]
 [name] [input name] [input expression] / [output name] [output expression]
.fam
.fi
.if n .RE
.SS "Categories"
.sp
Units inside the same category will be grouped together in the UI when
doing searches and other operations. A category is started using the
\f(CR!category\fP pragma which takes an identifier (\f(CRlower_snake_case\fP) and a
display name as a string literal.
.sp
.if n .RS 4
.nf
.fam C
!category us_survey "US survey measures"
.fam
.fi
.if n .RE
.SS "Base units"
.sp
Base units are impossible to define in terms of another unit without
creating a cycle. They represent fundamental physical quantities such as
time, length, temperature, etc.
.sp
The name is a shorthand form which is used when showing dimensionality
(for example, the dimensionality of \f(CRacceleration\fP is \f(CRm / s^2\fP), while
the long form is used for display purposes.
.sp
New base units should only be added when there is a clear value to doing
so. Examples include radians and bits.
.sp
.if n .RS 4
.nf
.fam C
?? Equal to the mass of the international prototype of the
?? kilogram. 3rd CGPM (1901, CR, 70).
kg        !kilogram
.fam
.fi
.if n .RE
.SS "Quantities"
.sp
Quantities are shown in parentheses whenever rink displays a unit.
They\(cqre very helpful for dimensional analysis, as it can be hard to
remember that \f(CRkg m^2 / s^2\fP means the physical quantity of energy.
.sp
Quantities are defined similar to units, but the definition starts with
a ? character. Quantities are in a separate namespace from units, so the
only valid names that can be used are the base units as well as other
quantities.
.sp
Unlike units, quantities have no numerical value (not even a value of
1 like SI derived units).
.sp
.if n .RS 4
.nf
.fam C
length                  ? meter
area                    ? length^2
.fam
.fi
.if n .RE
.SS "Prefixes"
.sp
Prefixes allow input of units like \f(CRgigabytes\fP, \f(CRmegameters\fP,
\f(CRkiloseconds\fP without needing to explicitly define each one in the units
database. Prefixes are always dimensionless.
.sp
These should not be added frequently, only when it\(cqs relevant to some
counting system. Examples include power of two byte prefixes (MiB, GiB,
etc.) and Dozenal prefixes.
.sp
Prefixes are split into two types, "long" prefixes and "short" prefixes.
Short prefixes should generally only be 1 letter. Typically, short
prefixes are aliases of their corresponding long prefix.
.sp
Prefixes are defined similar to other units, but the name ends with a
suffix of \f(CR\-\fP (long prefixes) or \f(CR\-\-\fP (short prefixes).
.sp
Prefixes use their own namespace. Their definitions can only reference
other prefixes, and not units.
.sp
.if n .RS 4
.nf
.fam C
kilo\-                   1e3
k\-\-                     kilo
.fam
.fi
.if n .RE
.SH "GUIDELINES"
.sp
These guidelines mainly apply when contributing to the upstream
\f(CRdefinitions.units\fP.
.sp
The units database should generally be wrapped so that it fits within
80 columns, for ease of reading. Similarly, units definitions should
generally be aligned vertically using spaces.
.sp
Non\-trivial units should generally have a documentation comment. This
comment can explain what the unit means, as well as providing a citation
for its value.
.sp
If there are multiple ways to interpret how a unit should be defined,
then mention which interpretation is being used. Unless it\(cqs implied by
the name (e.g. \f(CRsiderealyear\fP). Examples where units have multiple
interpretations include:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Customary units may vary by country, and may even vary depending on
which year in that country. Such as US, British, Australian, and
International definitions of the foot.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Units that are inherently fuzzy or represent multiple sources. This
may include days (calendar, sidereal), years (calendar, sidereal,
tropical), and others.
.RE
.sp
Doc comments should be written in US English. They should have sentence
capitalization and full stops, like this guide is written in. Avoid
run\-on sentences.
.sp
External links should include the protocol part (\f(CRhttps://\fP, \f(CRhttp://\fP).
They should be wrapped with angle brackets, like \f(CR\c
.URL "https://example.com" "" "\fP."
.sp
Dates should be written in a longhand format such as \f(CRJuly 5th, 1982\fP.
Do not use ambiguous formats like 2/3/99. It\(cqs often sufficient to only
state the year.
.sp
Comments in the definitions file are written for the benefit of other
maintainers. They can include explanations for why units are defined a
certain way. They can also state that certain units are part of a group
or set.
.sp
All units should be inside of a \f(CR!category\fP / \f(CR!endcategory\fP block.
Category blocks should also enclose comments related to that category,
and the \f(CR!category\fP pragma should immediately follow the last category\(cqs
\f(CR!endcategory\fP. This is to allow the file to be easily browsed using Vim
folds. The display name of a category should be in sentence case, and
should be aligned to the 70th column.
.SS "NAMING"
.sp
English names should be lowercase without separators. Words may be
separated by underscores when it adds clarity. Examples include \f(CRfoot\fP,
\f(CRolympiccubit\fP, \f(CRusgallon\fP.
.sp
If a shorthand is available, it should be added as an alias of the
longer name. Examples include \f(CRft\fP for \f(CRfoot\fP, \f(CRB\fP for \f(CRbyte\fP, and \f(CRΩ\fP
for \f(CRohm\fP.
.sp
.if n .RS 4
.nf
.fam C
ft                      foot
.fam
.fi
.if n .RE
.sp
Some units are most commonly written in a non\-Latin script. Use the
non\-Latin name as the canonical name, and add an ASCII\-based one as an
alias. Examples include \f(CRзолотник\fP, \f(CR分地\fP.
.sp
Some units are typically written with a symbol. Treat these similar to
the non\-Latin script names. Examples include \f(CRπ\fP (Pi), \f(CRτ\fP (Tau).
.sp
Legacy Unicode symbols should only be used as aliases of more standard
names. This includes uncommon symbols such as \f(CR㎒\fP (Unicode symbol for
Megahertz).
.sp
If there are multiple names for a unit, then the one that\(cqs most typical
should be the "canonical name". The canonical version should have the
full definition, and the other names should be added as aliases pointing
to the canonical version. Avoid duplicating the definition.
.SS "DEFINITIONS"
.sp
Units should be defined in terms of other related units when possible.
The expression you use to define the unit will be visible to the end
user. For example, a foot is defined as \f(CR12 inch\fP rather than as \f(CR304.8
mm\fP. This is because there is already a separate entry for \f(CRinch\fP
defined as \f(CR2.54 mm\fP. When displaying a unit\(cqs definition, Rink shows
both the original definition as well as the absolute value. So for
\f(CRfoot\fP it shows that it\(cqs defined as \f(CR12 inch\fP which equals \f(CR304.8
millimeter\fP.
.sp
Rink can represent arbitrary precision rational numbers. The only
limitation is how much memory is available. As a result, irrational
numbers like Pi or Euler\(cqs constant should be defined to at least 20
digits.
.sp
Universal constants that are measured experimentally should have as many
significant figures as are currently known. For example, if a number is
known to ±0.000003, then it should be listed to 6 digits after the
decimal point.
.SH "FILES"
.sp
Rink searches for the definitions file in these locations:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CR./rink/definitions.units\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CR$XDG_CONFIG_DIR/rink/definitions.units\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CR/usr/share/rink/definitions.units\fP
.RE
.sp
When live currency fetching is enabled, Rink also looks for a currency
file in these locations:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CR./rink/currency.units\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CR$XDG_CONFIG_DIR/rink/currency.units\fP
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
\f(CR/usr/share/rink/currency.units\fP
.RE
.SH "HISTORY"
.sp
Rink\(cqs units database was originally based on GNU Units and inherits
much of its syntax from there.
.sp
Notable differences include:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Removal of \f(CR!locale\fP, \f(CR!set\fP, \f(CR!utf8\fP, and other pragmas not used by Rink.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Addition of \f(CR!category\fP and \f(CR!endcategory\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Addition of documentation comments starting with \f(CR??\fP.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.  sp -1
.  IP \(bu 2.3
.\}
Addition of substances.
.RE
.SH "SEE ALSO"
.sp
rink(1), rink(5),
rink(7), rink\-dates(5)