non-decimal-units (10oct23)

git-svn-id: svn://tug.org/texlive/trunk@68504 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 288 insertions, 310 deletions

diff --git a/Master/texmf-dist/doc/latex/non-decimal-units/non-decimal-units.tex b/Master/texmf-dist/doc/latex/non-decimal-units/non-decimal-units.tex
index d5490aa0215..866efed85a2 100644
--- a/Master/texmf-dist/doc/latex/non-decimal-units/non-decimal-units.tex
+++ b/Master/texmf-dist/doc/latex/non-decimal-units/non-decimal-units.tex
@@ -1,15 +1,19 @@
 % !TEX TS-program = LuaLaTeX-shell-escape
-\documentclass{article}
+\documentclass[
+	a4paper,
+	margin=4cm
+]{article}
 
 \usepackage{non-decimal-units.preamble}
 
 \title{Non-Decimal Units for \LaTeX}
 \author{Mikkel Eide Eriksen\\\href{mailto:mikkel.eriksen@gmail.com}{\texttt{mikkel.eriksen@gmail.com}}}
 
-\nduset{
+\nduKeys{
 	set aligned for environment=tabular,
-	aliases/danish rigsdaler,
-	restrict segment depth=2,
+	tabularray column type=U,
+	unit depth=skilling,
+	unit separator={~},
 }
 
 \begin{document}
@@ -18,7 +22,7 @@
 
 \section{Preface} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-Many historical unit systems were non-decimal. For example, the Danish rigsdaler\footnote{\url{https://en.wikipedia.org/wiki/Danish_rigsdaler}} --- where 1 \nduName{danish rigsdaler}{0} consists of \nduFactor{danish rigsdaler}{1}~\nduName{danish rigsdaler}{1}, each again consisting of \nduFactor{danish rigsdaler}{2}~\nduName{danish rigsdaler}{2} for a total of 96 \nduName{danish rigsdaler}{2} per \nduName{danish rigsdaler}{0} --- was used from 1625 to 1875, when currency was decimalised to the current system of 1 krone = 100 øre.
+Many historical unit systems were non-decimal. For example, the Danish rigsdaler\footnote{\url{https://en.wikipedia.org/wiki/Danish_rigsdaler}} --- where 1 rigsdaler consists of 16~mark, each again consisting of 16~skilling for a total of 96 skilling per rigsdaler --- was used from 1625 to 1875, when currency was decimalised to the current system of 1 krone = 100 øre.
 
 % https://en.wikipedia.org/wiki/Non-decimal_currency
 
@@ -30,7 +34,7 @@ This package enables creation and configuration of such units to facilitate thei
 
 In order to do this, values are divided into \emph{segments}, which are separated by decimal points: for example, the historical Danish monetary value \nduValue{danish rigsdaler}{1.2.3} is entered as \texttt{1.2.3}, which the code then formats appropriately.
 
-Issues can be reported at \url{https://github.com/mikkelee/latex-units/issues} but keep in mind I am not very experienced with \LaTeX ;)
+Issues can be reported at \url{https://github.com/mikkelee/latex-units/issues}.
 
 \clearpage
 \section{Configuration} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
@@ -45,16 +49,16 @@ Where \meta{options} may contain one or more of the following unit systems. See
 
 \begin{description}
 \item[british] Currencies
-\item[danish] Currencies and areas
+\item[danish] Currencies, areas, and weights
 \item[german] Currencies
 \end{description}
 
-Alternately, one may configure new units via \refCom{nduNewUnit}.
+Alternately, one may configure new units via \refCom{nduNewBaseUnit} and \refCom{nduNewUnitGroup}.
 
 \end{docCommand}
 
 \begin{docCommand}
-	{nduset}
+	{nduKeys}
 	{\marg{options}}
 
 	Can be used to set options globally (in the preamble) or locally (in a group). See further documentation for possible keys/values.
@@ -70,18 +74,18 @@ The central macro is \docAuxCommand*{nduValue}. It formats values for display an
 
 \begin{docCommand}
 	{nduValue}
-	{\marg{unit name}\oarg{options}\marg{value}}
+	{\marg{unit group}\oarg{options}\marg{value}}
 
-Formats \meta{value} according to the setup configured for the \meta{unit name}, as well as any provided \meta{options}. The number of decimal points and the values between them determine how many and which segments are displayed.
+Formats \meta{value} according to the setup configured for the \meta{unit group}, as well as any provided \meta{options}.
 
-Empty segments are skipped, unless the \refKey{replace nil with} key is set.
+If no special configuration is made, the number of decimal points and the values between them determine how many and which units are displayed. For example, empty values are skipped unless the \refKey{replace nil with} key is set.
 	
 \begin{dispExample*}{
 	title=Example usage: \docAuxCommand*{nduValue} macro
 }
 \nduValue{danish rigsdaler}{1.2.3}\\
-\nduValue{danish rigsdaler}{1..}\\
-\nduValue{danish rigsdaler}{.2.}\\
+\nduValue{danish rigsdaler}{1}\\
+\nduValue{danish rigsdaler}{.2}\\
 \nduValue{danish rigsdaler}{..3}\\
 \end{dispExample*}
 \end{docCommand}
@@ -90,38 +94,56 @@ Empty segments are skipped, unless the \refKey{replace nil with} key is set.
 \subsubsection{Options}
 	
 \begin{docKeys}[
-		doc name = show,
+		doc name = display,
 	]{
 		{
-			doc parameter = {=values},
+			doc parameter = {=values only},
 		},
 		{
-			doc parameter = {=values and symbols},
-			doc description = initially \texttt{values and symbols},
+			doc parameter = {=formatted},
+			doc description = initially \texttt{formatted},
 		},
 		{
-			doc parameter = {=symbols},
+			doc parameter = {=symbols only},
+		},
+		{
+			doc parameter = {=numprint},
 		},
 	}
 
-Changes which information is included in the expansion.
+	Changes which information is included in the expansion.
 
-Because only those segments with a value will be included, \docAuxKey*{show}=\docValue*{symbols} can be used to list the segment units (though if only one or two is needed, it may be preferable to use \refCom{nduSymbol}).
+	Because only present values will be included, \docAuxKey*{display}=\docValue*{symbols only} can be used to list the segment units (though it may be preferable to use \refCom{nduHeader} or \refCom{nduSymbol}).
 
 \begin{dispExample}
 \nduValue{danish hartkorn}
-	[show=symbols]
+	[display=symbols only]
 	{0.0.0.0.0}
 
 \nduValue{danish hartkorn}
-	[show=symbols]
+	[display=values only]
 	{0.0...}
 \end{dispExample}
+	
+	Finally, it is possible to use the \href{https://ctan.org/pkg/numprint}{numprint} package to format numbers, especially useful for larger values. Note that this may be counter to the formatting of some units (eg. British pounds), in which case one may prefer the \docAuxKey{use numprint} key instead.
+
+\begin{dispExample}
+\nduValue{danish rigsdaler}
+	[display=numprint]
+	{1000}
+\end{dispExample}
 \end{docKeys}
 
-See also \cref{units:new} for further discussion on possible options.
+\begin{docKey}
+	{format}
+	{=\marg{...}}
+	{initially \docAuxCommand*{VALUE}\docAuxCommand*{nobreakspace}\docAuxCommand*{SYMBOL}}
+
+	Sets how a given base unit should be formatted for display.
+	
+	The placeholders \docAuxCommand*{VALUE} and \docAuxCommand*{SYMBOL} will be substituted when the value is typeset.
+\end{docKey}
 
-\clearpage
 \begin{docKeys}
 	[]
 	{
@@ -140,156 +162,117 @@ The key \docAuxKey*{replace nil with} replaces nil (empty) segments with a custo
 
 The key \docAuxKey*{treat zero as nil} replaces 0 with nothing, which in turn means that setting both will replace both zero and nil with the custom string.
 
-These keys also apply in non-tabular contexts, but are probably most useful here.
-
-\begin{dispExample*}{
-	title=Example usage: \docAuxKey*{replace nil with} key
-}
-\begingroup
-\nduset{
-	treat zero as nil,
-	replace nil with=---,
-}
-\begin{tabular}{r r}
-	\toprule
-	& \nduHeader{danish rigsdaler} \\
-	\midrule
-	a & \nduValue{danish rigsdaler}{1.2.3} \\
-	b & \nduValue{danish rigsdaler}{100.0.0} \\
-	c & \nduValue{danish rigsdaler}{.1.} \\
-	\bottomrule
-\end{tabular}
-\endgroup
-\end{dispExample*}
 \end{docKeys}
 
+\begin{docKey}
+	{unit depth}
+	{=\meta{unit name}}
+	{initially no restriction}
+	
+	When calculating or displaying a value, only the segments up to and including \meta{unit name} will be considered.
+	
+	In this document, the depth has been globally set to \texttt{skilling}, but older historical sub-units can be included by locally setting the depth to eg. \texttt{hvid} (or indeed not restricting it globally).
+	
+	If the \meta{unit name} is not present in the current unit group, it has no effect.
+	
+\begin{dispExample}
+\nduValue{danish rigsdaler}
+	[unit depth=skilling]
+	{1.2.3.4.5}
 
-\clearpage
-\subsection{Tabular Data} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-In order to align values in a tabular context, the \docAuxKey*{aligned} key causes \docAuxCommand{nduValue} to wrap each segment in a cell of equal width, using  \docAuxCommand*{makebox}.
-
-Additionally, the \docAuxCommand*{nduHeader} macro provides a convenient header showing the unit symbols.
-
-All segments will be included in the headers and cells, whether they contain a value or not. If no value is provided for the segment, and no nil replacement is specified with the \refKey{replace nil with} key, the cell will be empty.
-
-\begin{docCommand}
-	{nduHeader}
-	{\marg{unit name}\oarg{options}}
-	Formats the unit symbols in boxes suitable for a header. See \cpageref{units:new} for configuration of symbols.
-\end{docCommand}
-
-\clearpage
-\subsubsection{Options}
-
-\begin{docKeys}
-	[]
-	{
-		{
-			doc name = aligned,
-			doc description = {initially not set},
-		},
-		{
-			doc name = set aligned for environment,
-			doc description = {initially set for \texttt{tabular}},
-		},
-	}
+\nduValue{danish rigsdaler}
+	[unit depth=penning]
+	{1.2.3.4.5}
+\end{dispExample}
+\end{docKey}
 
-	Setting \docAuxKey*{aligned} will format the presently displayed header in aligned boxes, desirable in tabular contexts.
+\begin{docKey}
+	{unit separator}
+	{=\meta{...}}
+	{initially \docAuxCommand*{nobreakspace}}
+	
+	When displaying a value, this string will be inserted between each segment.
 
-	Additionally, the \docAuxKey*{set aligned for environment} key can be set to an environment name, causing \docAuxKey*{aligned} to automatically be set aligned for those enviroments, using \docAuxCommand*{AtBeginEnvironment}. It can be set multiple times, once for each required environment.
+\begin{dispExample}
+\nduValue{danish hartkorn}[
+		display=values only,
+		unit separator=.
+	]
+	{1.2.3.4}
 
-\begin{dispExample*}{
-	title=Example usage: \docAuxCommand*{nduHeader} and \docAuxCommand*{nduValue} macros with \docAuxKey*{aligned} key.
-}
-\begingroup
-\begin{tabular}{r r}
-	\toprule
-	  & \nduHeader{danish rigsdaler} \\
-	\midrule
-	a & \nduValue{danish rigsdaler}{1.2.3} \\
-	b & \nduValue{danish rigsdaler}{100..} \\
-	c & \nduValue{danish rigsdaler}{.1.} \\
-	\bottomrule
-\end{tabular}
-\endgroup
-\end{dispExample*}
+\nduValue{danish rigsdaler}
+	[unit separator={---}]
+	{1.2.3}
+\end{dispExample}
 
-\end{docKeys}
+\end{docKey}
 
 \begin{docKey}
-	{cell width}
-	{=\meta{length}}
-	{initially \texttt{5em}}
-
-Changes the width of each segment.
+	{use numprint}
+	{}
+	{not set initially}
+	
+	When displaying a value, use the \href{https://ctan.org/pkg/numprint}{numprint} package, including when using the \docAuxKey{format} key. You can of course also configure the numprint settings, either in a group or locally.
 
-\begin{dispExample*}{
-	title=Example usage: \docAuxKey*{cell width} key
-}
+\begin{dispExample}
 \begingroup
-\nduset{
-	cell width=3em,
-}
-\begin{tabular}{r r}
-	\toprule
-	& \nduHeader{danish rigsdaler} \\
-	\midrule
-	a & \nduValue{danish rigsdaler}{1.2.3} \\
-	b & \nduValue{danish rigsdaler}{100..} \\
-	c & \nduValue{danish rigsdaler}{.1.} \\
-	\bottomrule
-\end{tabular}
+\selectlanguage{ngerman}
+\nduValue{danish rigsdaler}
+	[use numprint]
+	{1000.0}
 \endgroup
-\end{dispExample*}
+\end{dispExample}
+
 \end{docKey}
 
 \clearpage
-\subsection{Arithmetical Operations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
-
-Basic arithmetic functions can be used to build a result for display. Internally, this is done by converting the value to a representation, which is the total number of the smallest usable unit, eg. \nduValue{danish rigsdaler}{1.2.3} is 131 \nduName{danish rigsdaler}{2}.
+\section{Arithmetical Operations} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-Results can be gathered in two ways, either manually via the \docAuxCommand*{nduMath} macro, or automatically via the \docAuxKey{add to variable} and \docAuxKey{subtract from variable} keys, the latter being especially suitable in tabular contexts.
-
-\begin{docCommands}[]{
-	{
-		doc name = nduMath,
-		doc parameter = \marg{unit name}\oarg{options}\marg{variable}\marg{operator}\marg{value}
-	},
-	{
-		doc name = nduResult,
-		doc parameter = \marg{unit name}\oarg{options}\marg{variable}
-	}
-}
+Basic arithmetic functions can be used to build a result for display. This is done by converting the value to an internal representation and storing it in a global variable. The first time a variable is used, it is assumed that the value is 0.
 
-The first arguments of \docAuxCommand*{nduMath} are identical to those of the \refCom{nduValue} macro. In addition, it has \meta{variable} and \meta{operator} (one of \texttt{+ - * /}) arguments. The first time a variable is used, it is assumed that the value is 0. The given value is then converted to its internal representation and stored in the variable. The command does not expand to any output.
+Results can be gathered in two ways, either manually via the \docAuxCommand*{nduMath} macro, or automatically via the \docAuxKey{add to variable} and \docAuxKey{subtract from variable} keys, the latter two being especially suitable in tabular contexts.
 
-Note that mixing units in the same variable is not currently supported, and will likely give incorrect results.
+\begin{docCommand}
+	{nduMath}
+	{\marg{unit name}\oarg{options}\marg{variable}\marg{operator}\marg{value}}
 
-The \docAuxCommand*{nduResult} macro takes a stored \meta{variable} and formats it for display in the same way as \refCom{nduValue}.
+	The first arguments of \docAuxCommand*{nduMath} are identical to those of the \refCom{nduValue} macro. In addition, it has \meta{variable} and \meta{operator} (one of \texttt{+ - * /}) arguments. The command does not expand to any output.
 
-Both may be further configured via the \meta{options} in the same way as the other macros.
+	Note that mixing unit groups in the same variable is not currently supported, and will likely give incorrect results.
 
 \begin{dispExample*}{
-	title=Example usage: \docAuxCommand*{nduMath} and \docAuxCommand*{nduResult} macros
+	title=Example usage: \docAuxCommand*{nduMath} macro
 }
 \nduMath{danish rigsdaler}{example 1}{+}{0.0.10}
 \nduMath{danish rigsdaler}{example 1}{+}{..8}
 \nduMath{danish rigsdaler}{example 1}{+}{0.2}
 \nduMath{danish rigsdaler}{example 1}{+}{0.5.1}
-\nduResult{danish rigsdaler}{example 1} % = 1.2.3
+% there is no output, the result 1.2.3
+% will be seen in the following example.
 \end{dispExample*}
 
+\end{docCommand}
+
+\begin{docCommand}
+	{nduResult}
+	{\marg{unit name}\oarg{options}\marg{variable}}
+
+	The \docAuxCommand*{nduResult} macro takes a stored \meta{variable} and formats it via \meta{options} for display in the same way as \refCom{nduValue}.
+
 \begin{dispExample*}{
 	title=Example usage: \docAuxCommand*{nduResult} macro
 }
-\nduHeader{danish rigsdaler}\\
-\nduResult{danish rigsdaler}[aligned]{example 1}
+\nduResult{danish rigsdaler}{example 1} % = 1.2.3
+
+And let's add an additional 15 skilling:
+\nduMath{danish rigsdaler}{example 1}{+}{0.0.15}
+\nduResult{danish rigsdaler}{example 1} % = 1.3.2
 \end{dispExample*}
-\end{docCommands}
+
+\end{docCommand}
 
 \clearpage
-\subsubsection{Options}
+\subsection{Options for Arithmetical Operations}
 
 \begin{docKeys}
 	[
@@ -304,14 +287,13 @@ Both may be further configured via the \meta{options} in the same way as the oth
 		},
 	}
 
-Setting either of these keys will cause all uses of \docAuxCommand*{nduValue} in the current group to be added to or subtracted from the variable with the given name.
+Setting either of these keys will cause all uses of \docAuxCommand*{nduValue} in the current group to be added to or subtracted from the variable with the given name. It can of course also be set on individual invocations of the command.
 
 \begin{dispExample*}{
 	title=Example usage: \docAuxKey*{add to variable} key
 }
 \begingroup
-\nduset{
-	cell width=3em,
+\nduKeys{
 	replace nil with=---,
 	add to variable=example 2
 }
@@ -321,22 +303,12 @@ Setting either of these keys will cause all uses of \docAuxCommand*{nduValue} in
 	\midrule
 	a & \nduValue{danish rigsdaler}{1.2.3} \\
 	b & \nduValue{danish rigsdaler}{100.1.} \\
-	\bottomrule
+	\midrule
 	total & \nduResult{danish rigsdaler}{example 2} \\ % = 101.3.3
+	\bottomrule
 \end{tabular}
 \endgroup
 \end{dispExample*}
-
-Results are global and remain accessible outside the group:
-\begin{dispExample}
-\nduResult{danish rigsdaler}{example 2}
-\end{dispExample}
-
-Adding an additional 15 \nduName{danish rigsdaler}{2} to the existing result gives:
-\begin{dispExample}
-\nduMath{danish rigsdaler}{example 2}{+}{0.0.15}
-\nduResult{danish rigsdaler}{example 2} % = 101.4.2
-\end{dispExample}
 \end{docKeys}
 
 \begin{docKey}
@@ -349,38 +321,151 @@ Reformats an amount, which is useful for quick conversions.
 \begin{dispExample*}{
 	title=Example usage: \docAuxKey*{normalize} key
 }
-100 \nduName{danish rigsdaler}{2} equal
+100 skilling equal
 \nduValue{danish rigsdaler}[normalize]{..100} % 1.0.4
 \end{dispExample*}
 \end{docKey}
 
+\clearpage
+\section{Tabular Data} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-\section{Accessing Information About Units} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+There are a couple of ways to display values in tabular context, centered around explicitly or implicitly setting the \docAuxKey{aligned} key, which causes \docAuxCommand{nduValue} to wrap each segment in a cell of configurable width.
+
+Additionally, all segments will be included in headers and cells, whether they contain a value or not (provided \docAuxKey{unit depth} allows it). If no value is provided for the segment, and no nil replacement is specified with the \refKey{replace nil with} key, the cell will be empty.
 
 \begin{docCommand}
-	{nduName}
-	{\marg{unit name}\marg{segment}}
-	Expands to the name of the the given segment of the unit.
-	
-	Set by \refKey{segment:name}.
+	{nduHeader}
+	{\marg{unit name}\oarg{options}}
+	Convenient header showing the unit symbols. See \cpageref{units:new} for configuration of symbols.
 \end{docCommand}
 
+\subsection{Options for Tabular Data}
+
+\begin{docKey}
+	{aligned}
+	{}
+	{initially not set}
+
+Causes each value to be wrapped in right-aligned cells of configurable width.
+\end{docKey}
+
+\begin{docKey}
+	{cell widths}
+	{=\meta{length}}
+	{initially \texttt{3em}}
+
+Changes the width of each cell. One may supply a bracketed comma-separated list of widths. If the list is shorter than the number of base units in the group, the last width will be repeated. See page \pageref{example:table:widths} for example.
+\end{docKey}
+
+\begin{docKeys}
+	[]
+	{
+		{
+			doc name = set aligned for environment,
+			doc parameter = {=\meta{name}},
+			doc description = {initially not set},
+		},
+		{
+			doc name = tabularray column type,
+			doc parameter = {=\meta{letter}},
+			doc description = {initially not set},
+		},
+	}
+
+	The \docAuxKey{set aligned for environment} key can be set to an environment name, causing \docAuxKey*{aligned} to automatically be set for those enviroments, using \docAuxCommand*{AtBeginEnvironment}. It can be set multiple times, once for each required environment. See page \pageref{example:table:environment} for example.
+
+	The \docAuxKey{tabularray column type} key can be used to create a column type, which automatically wraps the column contents in \docAuxCommand{nduValue}. The column type takes two arguments, a unit group and a set of key values for further configuration. Additionally, the special values \texttt{HEADER},  \texttt{RESULT}, and \texttt{SKIP} will respectively use \docAuxCommand{nduHeader}, \docAuxCommand{nduResult}, and skip the cell. See page \pageref{example:table:tabularray} for example\footnote{Thanks to Yukai Chou for help with \href{https://github.com/lvjr/tabularray}{tabularray} integration.}.
+
+\end{docKeys}
+
+\begin{dispExample*}{
+	title=Example of tabular data using \docAuxKey{set aligned for environment},
+	label=example:table:environment
+}
+\begingroup
+\nduKeys{
+%	has been set in this document's preamble:
+%	set aligned for environment=tabular,
+	treat zero as nil,
+	replace nil with=---,
+}
+\begin{tabular}{r r}
+	\toprule
+	& \nduHeader{danish rigsdaler} \\
+	\midrule
+	a & \nduValue{danish rigsdaler}{1.2.3} \\
+	b & \nduValue{danish rigsdaler}{100.0.0} \\
+	c & \nduValue{danish rigsdaler}{.1.} \\
+	\bottomrule
+\end{tabular}
+\endgroup
+\end{dispExample*}
+
+\begin{dispExample*}{
+	title=Example usage: \docAuxKey*{cell widths} key,
+	label=example:table:widths
+}
+\begingroup
+\nduKeys{
+	cell widths={5em, 1.5em},
+}
+\begin{tabular}{r r}
+	\toprule
+	& \nduHeader{danish rigsdaler} \\
+	\midrule
+	a & \nduValue{danish rigsdaler}{1.2.3} \\
+	b & \nduValue{danish rigsdaler}{100..} \\
+	c & \nduValue{danish rigsdaler}{.1.} \\
+	\bottomrule
+\end{tabular}
+\endgroup
+\end{dispExample*}
+
+\begin{dispExample*}{
+	title=Example of tabular data using \docAuxKey{tabularray column type},
+	label=example:table:tabularray
+}
+\begingroup
+%	has been set in this document's preamble:
+%	tabularray column type=U
+\begin{tblr}{
+	r
+	U{danish rigsdaler}{add to variable=table result 1}|
+	U{danish rigsdaler}{add to variable=table result 2}
+}
+	\toprule
+	& HEADER & HEADER\\
+	\midrule
+	a & 1.2.3 & ..15 \\
+	b & 100.0.0 & ..10 \\
+	c & .1. & ..2 \\
+	\midrule
+	total & RESULT & RESULT \\
+	\bottomrule
+\end{tblr}
+\endgroup
+\end{dispExample*}
+
+\clearpage
+\section{Accessing Information About Units} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
 \begin{docCommand}
 	{nduSymbol}
-	{\marg{unit name}\marg{segment}}
-	Expands to the symbol of the the given segment of the unit.
+	{\marg{unit name}}
+	Expands to the symbol of the given base unit.
 	
-	Set by \refKey{segment:symbol}.
+	Set by \refKey{units:symbol}.
 \end{docCommand}
 
 \begin{docCommand}
 	{nduFactor}
-	{\marg{unit name}\marg{segment}}
-	Expands to the conversion factor of the the given segment of the unit, ie. how many of the underlying segment the given segment consists of.
+	{\marg{unit name}\marg{unit name}}
+	Expands to the conversion between two base units.
 
+	Set by \refKey{units:factor}.
 \begin{dispExample}
-That is, 1 \nduName{danish rigsdaler}{0} consists of
-\nduFactor{danish rigsdaler}{1} \nduName{danish rigsdaler}{1}.
+That is, 1 \nduSymbol{rigsdaler} consists of
+\nduFactor{rigsdaler}{skilling} \nduSymbol{skilling}.
 \end{dispExample}
 \end{docCommand}
 
@@ -391,156 +476,66 @@ That is, 1 \nduName{danish rigsdaler}{0} consists of
 If the included units are not suitable, more can be created. Pull requests are also welcome at \url{https://github.com/mikkelee/latex-units}.
 
 \begin{docCommand}
-	{nduNewUnit}
+	{nduNewBaseUnit}
 	{\marg{unit name}\marg{key/value pairs}}
 	
-Units can have up to 7 segments, numbered \meta{0-6}. The left-most segment, that is, the \emph{top} or \emph{root} segment, is numbered \texttt{0}.
-
-The numeral part of the below key paths \docAuxKey*{segment 0/} can be any integer up to \texttt{6}, ie. \docAuxKey*{segment 6/}. The internal number of segments is determined by how many name keys are created.
-
-See below for available settings.
+Creates a new base unit. It must contain at least a \docAuxKey{symbol}, but a \docAuxKey{factor} is also required for the math functions (see below).
 
 \end{docCommand}
 
 \begin{docCommand}
-	{nduNewMacro}
-	{\marg{unit name}\oarg{key/value pairs}\marg{control sequence}}
+	{nduNewUnitGroup}
+	{\marg{unit name}\oarg{key/value pairs}\marg{ordered base units}\oarg{control sequence}}
 
-	It is possible to create shortcut macros for commonly used \meta{unit name}s with optional overriding options.
+	In order for the math functions to work, every base unit in the group must have a conversion path to the right-most base unit, eg. if a unit group consists of base units \texttt{A, B, C}, there must be defined factors for \texttt{B\rightarrow C} and either \texttt{A\rightarrow C} or \texttt{A\rightarrow B}; if only the latter is configured, an attempt to calculate and cache it will be made internally.
 
-	These macros take the same arguments as the full \refCom{nduValue} macro, except without the first argument (ie. the name of the unit).
+	It is possible to create shortcut macros for commonly used unit groups with optional overriding options. These macros take the same arguments as the full \refCom{nduValue} macro, except without the first argument (ie. the name of the unit).
+	
+	Including several sub units may make the math results awkward, as the algorithm is greedy.
 
 \begin{dispExample}
-\nduNewMacro{rigsdaler.mark.skilling}
-	[unit groups/rigsdaler.mark.skilling/segment 0/symbol={R\textsuperscript{dl}}]
-	{myRdl}
-\myRdl{1.2.3}
+\nduNewUnitGroup{my sletdaler}
+	[units/sletdaler/symbol={Sletd.}]
+	{sletdaler, ort, skilling}
+	[\mySldl]
+\mySldl{1.2.3}
 \end{dispExample}
 
 \end{docCommand}
 
-%\begin{docCommand}
-%	{nduCommonSymbols}
-%	{\marg{key/value pairs}}
-%
-%	It is possible to configure commonly used symbols using the form \texttt{\meta{name}=\meta{symbol}}. These will be used as fallbacks if no specific symbol is configured for a segment via \refKey{segment:symbol}.
-%
-%\end{docCommand}
-%
-%\begin{docCommand}
-%	{nduCommonFactors}
-%	{\marg{key/value pairs}}
-%
-%	Not currently implemented.
-%
-%\end{docCommand}
-
 \clearpage
-\subsubsection{Options}
-
-\begin{docKey}
-	{segment separator}
-	{=\meta{...}}
-	{initially \texttt{\~{}}}
-	
-	When displaying a value, this string will be inserted between each segment.
-
-\begin{dispExample}
-\nduValue{danish hartkorn}[
-		show=values,
-		segment separator=.
-	]
-	{1.2.3.4}
-
-\nduValue{danish rigsdaler}
-	[segment separator={---}]
-	{1.2.3}
-\end{dispExample}
-
-\end{docKey}
-
-\begin{docKey}
-	{restrict segment depth}
-	{=\meta{integer}}
-	{initially no restriction}
-	
-	When calculating or displaying a value, only the segments up to and including \meta{integer} will be considered.
-	
-	In this document, the depth has been globally set to \texttt{2} for \docAuxKey*{danish rigsdaler}, but the older historical sub-unit \nduName{danish rigsdaler}{3} can be included by locally setting the depth to \texttt{3} (or indeed not restricting it globally).
-	
-\begin{dispExample}
-\nduValue{danish rigsdaler}
-	[restrict segment depth=3]
-	{1.2.3.4}
-\end{dispExample}
-\end{docKey}
-
-\begin{docKey}
-	[]
-	[doc label=segment:name]
-	{segment \meta{n}/name}
-	{=\meta{name}}
-	{no default, initially undefined}
-
-	Gives the proper name of the segment's unit. Used internally to determine how many segments the unit contains.
-	
-	Can be accessed with by \refCom{nduName}.
-\end{docKey}
+\subsection{Options For Base Units}
 
 \begin{docKey}
 	[]
-	[doc label=segment:symbol]
-	{segment \meta{n}/symbol}
+	[doc label=units:symbol]
+	{units/\meta{unit name}/symbol}
 	{=\meta{symbol}}
-	{no default, initially undefined}
+	{}
 
-	Configures a symbol displaying the unit. This is used in \docAuxCommand{nduHeader} and is also available via \docAuxCommand{nduSym} when defining the \refKey{segment:display} (see below).
-	
-	If none is configured, an attempt to look up a common symbol by its name is made. These can be configured with \refCom{nduCommonSymbols}.
+	Configures a symbol displaying the unit. This is used in \docAuxCommand{nduValue}, \docAuxCommand{nduHeader}, and is also available via \docAuxCommand*{SYMBOL} when defining the \refKey{units:format} (see also \refKey{}).
 \end{docKey}
 
-\begin{docKeys}
-	[
-		doc parameter = {=\meta{...}},
-	]
-	{
-		{
-			doc name = {segment \meta{n}/prefix},
-			doc label = segment:prefix,
-			doc description = {initially set to \texttt{\{\}}},
-		},
-		{
-			doc name = {segment \meta{n}/suffix},
-			doc label = segment:suffix,
-			doc description = {initially set to \texttt{\{~\docAuxCommand*{nduSym}\}}},
-		},
-	}
-
-	When displaying a value, segments will be wrapped between the \meta{prefix} and \meta{suffix}.
-	
-	The macro \docAuxCommand{nduSym} is available here to show the symbol configured for the segment.
-\end{docKeys}
-
 \begin{docKey}
 	[]
-	[doc label=segment:display]
-	{segment \meta{n}/display}
-	{=\marg{prefix}\marg{suffix}}
+	[doc label=units:format]
+	{units/\meta{unit name}/format}
+	{=\marg{...}}
 	{}
 
-	Sets both \refKey{segment:prefix} and \refKey{segment:suffix} at the same time.
+	Sets how a given base unit should be formatted for display. If none is given, the general top-level \docAuxKey{format} key is used.
 \end{docKey}
 
 \begin{docKey}
 	[]
-	[doc label=segment:factor]
-	{segment \meta{n}/factor}
-	{=\meta{integer}}
-	{no default, initially undefined}
+	[doc label=units:factor]
+	{units/\meta{unit name}/factor}
+	{=\meta{integer} \meta{unit name}}
+	{}
 	
-	The conversion factor of a segment is how many of the underlying segment the given segment consists of.
+	The conversion factor of a unit is how many of an underlying unit the given unit consists of. This can be specified multiple times.
 	
-	This is used in the math macros, in order to calculate the correct segment values.
+	This is used by the math macros and keys to calculate the sums and products.
 	
 	Can be accessed via \refCom{nduFactor}.
 \end{docKey}
@@ -549,39 +544,22 @@ These keys can of course also be set temporarily in \refCom{nduValue}
 
 \begin{dispExample}
 \nduValue{danish rigsdaler}
-	[segment 1/symbol=Mk.]
+	[units/mark/symbol=Mk.]
 	{.9.}
 
 \nduValue{danish rigsdaler}
-	[segment 0/display={}{~Rigsdaler og}]
+	[units/rigsdaler/format={\VALUE~Rigsdaler og}]
 	{1.2.3}
 
 \nduValue{danish rigsdaler}[
-		segment separator={---},
-		segment 0/display={(}{)},
-		segment 1/display={[}{]},
-		segment 2/display={\{}{\}},
+		unit separator={---},
+		units/rigsdaler/format={(\VALUE)},
+		units/mark/format={[\VALUE]},
+		units/skilling/format={\{\VALUE\}},
 	]
 	{1.2.3}
 \end{dispExample}
 
-\begin{docKey}
-	{create macro named}
-	{=\meta{control sequence}}
-	{no default, initially empty}
-	
-	Units may provide a default shortcut macro, for example the \docValue*{danish rigsdaler} unit configures \docAuxCommand*{rdl}.
-	
-	This is done via \refCom{nduNewMacro} which describes the arguments of the resulting macros.
-
-\begin{dispExample*}{
-	sidebyside,
-	righthand width=1.75cm,
-}
-\rdl{2.3.}
-\end{dispExample*}
-\end{docKey}
-
 \clearpage
 \section{Included Units} %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%