summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/siunitx/siunitx.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/siunitx/siunitx.tex')
-rw-r--r--macros/latex/contrib/siunitx/siunitx.tex82
1 files changed, 73 insertions, 9 deletions
diff --git a/macros/latex/contrib/siunitx/siunitx.tex b/macros/latex/contrib/siunitx/siunitx.tex
index 3cb5f25ed5..76afc34861 100644
--- a/macros/latex/contrib/siunitx/siunitx.tex
+++ b/macros/latex/contrib/siunitx/siunitx.tex
@@ -1593,7 +1593,6 @@ conveys. The options are summarised in Table~\ref{tab:opt:num:out}.
\end{table}
\DescribeOption{group-digits}
-\DescribeOption{group-four-digits}
\DescribeOption{group-separator}
Grouping digits into blocks of three is a common method to increase the ease of
reading of numbers. The \opt{group-digits} choice controls whether this
@@ -2849,19 +2848,14 @@ letters may be used: these must be single tokens. For example, provided the
\pkg{numprint} package has not been loaded, the letter |n| could be used as
this would suggest a numerical column.
-\section{Upgrading from version~\texorpdfstring{$2$}{2}}
+\section{Upgrading from version~\texorpdfstring{$2$}{2}%
+ \label{sec:upgrading}}
The package has been largely re-written internally between versions $2$ and
$3$. A significant number of key--value settings have new, more descriptive,
names. Where possible, older names are mapped to newer ones internally: you
will be warned in the log if this is the case.
-Updating to the latest edition of the \acro{SI} Brochure means that a small
-number of unit macros have been removed: of those accepted for use,
-\cs{angstrom} is no longer present, whilst the units determined experimentally
-are all no longer listed (\cs{atomicmassunit}, \cs{bohr}, \cs{clight},
-\cs{electronmass}, \cs{elementarycharge}, \cs{hartree}, \cs{planckbar}).
-
It is possible to use the \LaTeXe{} kernel mechanism to load the last
version~$2$ release for documents that cannot be successfully processed using
version~$3$. This can be achieved using
@@ -2936,6 +2930,54 @@ or
If you are using \opt{table-column-width} to have fixed-width columns, you
also now need \opt{table-fixed-width} to set this option active.
+Direct support for loading a local configuration file, \texttt{siunitx.cfg},
+has been removed. However, the approach described in
+Section~\ref{sec:hint:config} may be used to achieve the same effect with the
+additions more clearly shown in document sources.
+
+\section{Unit changes made by \acro{BIPM}%
+ \label{sec:BIPM8}}
+
+In addition to the changes in the \pkg{siunitx} package described in
+Section~\ref{sec:upgrading}, there are changes in the units defined by the
+\acro{BIPM} in the 9th Edition of the \acro{SI} Brochure which are reflected
+here. There are two major areas of change.
+
+The first is in respect of units accepted for use with \acro{SI} units. In the
+8th Edition of the \acro{SI} Brochure, the following units were listed as
+accepted for use in specialist fields
+\begin{itemize}
+ \item ångström (\cs{angstrom})
+ \item bar (\cs{bar})
+ \item barn (\cs{barn})
+ \item knot (\cs{knot})
+ \item millimetre of mercury (\cs{mmHg})
+ \item nautical mile (\cs{nauticalmile})
+\end{itemize}
+These are no longer listed in the 9th Edition, and so are deprecated as
+pre-defined units by \pkg{siunitx}. These units will issue a warning on first
+use, and users should add their own definitions to the start of their sources
+to avoid this.
+
+Secondly, the move to a new definition of base units means that the table of
+units determined experimentally has been removed from the \acro{SI} Brochure.
+This covers the following units defined by \pkg{siunitx} in previous releases
+\begin{itemize}
+ \item \cs{bohr}
+ \item \cs{clight}
+ \item \cs{electronmass}
+ \item \cs{elementarycharge}
+ \item \cs{hartree}
+ \item \cs{planckbar}
+\end{itemize}
+These are also deprecated in \pkg{siunitx} and users should provide their own
+definitions.
+
+In addition to these two major blocks, the unit \cs{atomicmassunit} has similar
+deprecated status: this was listed as with experimentally-determined units in
+the 8th Edition of the \acro{SI} Brochure but is equivalent to the dalton, a
+unit which remains accepted.
+
\section{Localisation}
The \pkg{translations} package provides a structured framework for localisation
@@ -3346,7 +3388,7 @@ output mode is known. It may be necessary to make some tokens robust using
\qty{0,4066\dots}{\metre\squared}
\end{LaTeXdemo}
-\subsection{Demonstrating prefixes
+\subsection{Demonstrating prefixes%
\label{sec:hint:prefixes}}
As \pkg{siunitx} contains data about the numerical values of unit prefixes,
@@ -3372,6 +3414,28 @@ This may be conveniently wrapped up inside a document command, for example
}
\end{LaTeXdemo}
+\subsection{Creating a set of pre-defined units%
+ \label{sec:hint:config}}
+
+There are many units which sit outside of those defined in the (current)
+\acro{SI} Brochure which are of use to many people. Most obvious are those
+which have been detailed in previous editions of the Brochure, as described
+in Section~\ref{sec:BIPM8}, but there are many others.
+
+It is often convenient to have a pre-defined set of useful units available
+without needing to copy the full set of definitions into each source file. At
+the same time, it is important that such sources do show that they are using
+units not defined by the core part of \pkg{siunitx}. The most straight-forward
+way to acheive this is to create a separate file, for example
+\texttt{siunitx-local-units.tex}, and place it in your local \TeX{} tree
+(usually \verb|~/texmf/tex/latex/| on Linux, \verb|~/Library/texmf/tex/latex/|
+on macOS or \verb|C:\Users\<name>\texmf\tex\latex| on Windows). This can then
+be loaded in the preamble using
+\begin{LaTeXdemo}[code only]
+ % Load useful 'local' units
+ \input{siunitx-local-units}
+\end{LaTeXdemo}
+
\section{Using (\acro{SI}) units}
Consistent and logical units are a necessity for scientific work, and have