.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "s1kd-uom" "1" "2021-04-16" "" "s1kd-tools"
.hy
.SH NAME
.PP
s1kd-uom - Convert units of measure in quantity data
.SH SYNOPSIS
.IP
.nf
\f[C]
s1kd-uom [-dflqv,.h?] [-D <fmt>] [-F <fmt>]
         [-u <uom> -t <uom> [-e <expr>] [-F <fmt>] ...]
         [-s <name>|-S <path> ...] [-U <path>] [-p <fmt> [-P <path>]]
         [<object>...]
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[I]s1kd-uom\f[R] tool converts between specified units of measure
in quantity data, for example, to automatically localize units of
measure in data modules.
.SH OPTIONS
.TP
-D, --duplicate-format <fmt>
Specify a custom format for duplicating quantities (-d).
The \[aq]%\[aq] character acts as a placeholder for the duplicate
quantity value.
The default format for -d is equivalent to \f[C]-D \[aq] (%)\[aq]\f[R].
.TP
-d, --duplicate
When converting, instead of overwriting the original quantity, include
the converted quantity after the original in parenthesis.
For example, \[dq]200 mm\[dq] when converting mm to in would become
\[dq]200 mm (7.87 in)\[dq].
.TP
-e, --formula <expr>
Specify the formula for a conversion, given as an XPath expression.
.TP
-F, --format <fmt>
Specify the format for quantity values.
When used before -u, this specifies the default format for all
conversions.
Otherwise, this specifies the format for each individual conversion.
Formats specified for individual conversions override the default format
set for all conversions.
.TP
-f, --overwrite
Overwrite input CSDB objects.
.TP
-h, -?, --help
Show help/usage message.
.TP
-l, --list
Treat input (stdin or arguments) as lists of filenames of CSDB objects
to list references in, rather than CSDB objects themselves.
.TP
-P, --uomdisplay <path>
Use a custom \f[C].uomdisplay\f[R] file.
.TP
-p, --preformat <fmt>
Preformat quantity data to the specified decimal format.
The built-in formats are:
.RS
.IP \[bu] 2
SI - comma for decimal separator, space for grouping
.IP \[bu] 2
euro - comma for decimal separator, full-stop for grouping
.IP \[bu] 2
imperial - full-stop for decimal separator, comma for grouping
.RE
.TP
-q, --quiet
Quiet mode.
Errors are not printed.
.TP
-S, --set <path>
Apply a set of conversions defined in an XML file.
.TP
-s, --preset <name>
Apply a set of predefined conversions.
The available presets are:
.RS
.IP \[bu] 2
SI - convert imperial/US customary units to SI units.
.IP \[bu] 2
imperial - convert SI units to British imperial units.
.IP \[bu] 2
US - convert SI units to US customary units.
.RE
.TP
-t, --to <uom>
Unit of measure to convert to.
.TP
-U, --uom <path>
Use a custom \f[C].uom\f[R] file.
.TP
-u, --from <uom>
Unit of measure to convert from.
.TP
-v, --verbose
Verbose output.
.TP
-,, --dump-uom
Dump the default \f[C].uom\f[R] file.
.TP
-., --dump-uomdisplay
Dump the default \f[C].uomdisplay\f[R] file.
.TP
--version
Show version information.
.TP
<object>
CSDB objects to convert quantities in.
.PP
In addition, the following options allow configuration of the XML
parser:
.TP
--dtdload
Load the external DTD.
.TP
--huge
Remove any internal arbitrary parser limits.
.TP
--net
Allow network access to load external DTD and entities.
.TP
--noent
Resolve entities.
.TP
--parser-errors
Emit errors from parser.
.TP
--parser-warnings
Emit warnings from parser.
.TP
--xinclude
Do XInclude processing.
.TP
--xml-catalog <file>
Use an XML catalog when resolving entities.
Multiple catalogs may be loaded by specifying this option multiple
times.
.SS \f[C].uom\f[R] file
.PP
This file contains the rules for converting units of measure.
If no specific conversions are given with the -u and -t options, this
file also acts as a list of all conversions to perform.
.PP
By default, the program will search the current directory and parent
directories for a file named \f[C].uom\f[R], but any file can be
specified by using the -U option.
.PP
Example of a \f[C].uom\f[R] file:
.IP
.nf
\f[C]
<uom>
<convert from=\[dq]degF\[dq] to=\[dq]degC\[dq] formula=\[dq]($value - 32) * (5 div 9)\[dq]/>
<convert from=\[dq]in\[dq] to=\[dq]cm\[dq] formula=\[dq]$value * 2.54\[dq]/>
<convert from=\[dq]lbm\[dq] to=\[dq]kg\[dq] formula=\[dq]$value div 2.205\[dq]/>
</uom>
\f[R]
.fi
.PP
The tool contains a default set of rules for common units of measure.
This can be used to create a default \f[C].uom\f[R] file by use of the
-, option:
.IP
.nf
\f[C]
$ s1kd-uom -, > .uom
\f[R]
.fi
.PP
To select only certain common rules when generating a \f[C].uom\f[R]
file, the -u and -t options can be used:
.IP
.nf
\f[C]
$ s1kd-uom -, -u in -t cm -u degF -t degC > .uom
\f[R]
.fi
.PP
This will generate a \f[C].uom\f[R] file containing rules to convert
inches to centimetres, and degrees Fahrenheit to degrees Celsius.
.PP
The same file format is used with the -S option to specify a set of
conversions to perform.
In this case, the attribute \f[C]formula\f[R] is optional, as the
default formula or the formula in the \f[C].uom\f[R] file will be used
if it is not specified.
.SS Conversion formula variables (-e)
.PP
When specifying a formula for conversion, the following variables can be
used:
.TP
\f[B]\f[CB]$pi\f[B]\f[R]
The constant \[*p]
.TP
\f[B]\f[CB]$value\f[B]\f[R]
The original quantity value
.PP
For example, the formula to convert degrees to radians can be given as
follows:
.PP
\f[C]$value * ($pi div 180)\f[R]
.SS Preformatting UOMs (-p) and the \f[C].uomdisplay\f[R] file
.PP
The tool can also convert semantic quantity data to presentation
quantity data.
The -p option specifies which conventions to use for formatting quantity
values.
For example:
.IP
.nf
\f[C]
<para>Tighten the
<quantity>
<quantityGroup>
<quantityValue quantityUnitOfMeasure=\[dq]cm\[dq]>6.35</quantityValue>
</quantityGroup>
</quantity>
bolt.</para>
\f[R]
.fi
.IP
.nf
\f[C]
$ s1kd-uom -p SI <DM>
\f[R]
.fi
.IP
.nf
\f[C]
<para>Tighten the 6,35 cm bolt.</para>
\f[R]
.fi
.PP
This can also be combined with UOM conversions:
.IP
.nf
\f[C]
$ s1kd-uom -u cm -t in -p imperial <DM>
\f[R]
.fi
.IP
.nf
\f[C]
<para>Tighten the 2.5 in bolt.</para>
\f[R]
.fi
.PP
Custom formats for values or UOMs can be defined in the
\f[C].uomdisplay\f[R] file.
By default, the tool will search the current directory and parent
directories for a file named \f[C].uomdisplay\f[R], but any file can be
specified by using the -P option.
.PP
Example of a \f[C].uomdisplay\f[R] file:
.IP
.nf
\f[C]
<uomDisplay>
<format name=\[dq]custom\[dq] decimalSeparator=\[dq],\[dq] groupingSeparator=\[dq].\[dq]/>
<uoms>
<uom name=\[dq]cm\[dq]> cm</uom>
<uom name=\[dq]cm2\[dq]> cm<superScript>2</superScript></uom>
</uoms>
<currencies>
<currency name=\[dq]CAD\[dq]>
<prefix>$</prefix>
<postfix> CAD</postfix>
</currency>
<currency name=\[dq]GBP\[dq]>
<prefix>\[Po]</prefix>
<postfix> GBP</postfix>
</currency>
</currencies>
</uomDisplay>
\f[R]
.fi
.PP
Units of measure and currencies that are not defined will be presented
as their name (e.g., \[dq]cm2\[dq]) separated from the value by a space.
.PP
More complex UOM display, such as pluralization of units of measure, can
be accomplished with embedded XSLT in the \f[C].uomdisplay\f[R] file:
.IP
.nf
\f[C]
<uoms
xmlns:xsl=\[dq]http://www.w3.org/1999/XSL/Transform\[dq]>
<xsl:variable name=\[dq]value\[dq] select=\[dq]parent::*/>
<uom name=\[dq]in\[dq]>
<xsl:text> </xsl:text>
<xsl:choose>
<xsl:when test=\[dq]$value = 1\[dq]>inch</xsl:when>
<xsl:otherwise>inches</xsl:otherwise>
</xsl:choose>
</uom>
<uom name=\[dq]ft\[dq]>
<xsl:text> </xsl:text>
<xsl:choose>
<xsl:when test=\[dq]$value = 1\[dq]>foot</xsl:when>
<xsl:otherwise>feet</xsl:otherwise>
</xsl:choose>
</uom>
</uoms>
\f[R]
.fi
.PP
The context for the embedded XSLT is the unit of measure attribute on
the value, tolerance or group.
XSLT elements in the \f[C]<uoms>\f[R] element will be processed for all
units of measure, while XSLT elements in \f[C]<uom>\f[R] elements will
only apply to an individual unit of measure.
.PP
The tool contains a default set of formats and displays.
These can be used to create a default \f[C].uomdisplay\f[R] file by use
of the -.
option:
.IP
.nf
\f[C]
$ s1kd-uom -. > .uomdisplay
\f[R]
.fi
.SH EXAMPLES
.SS Common units of measure
.PP
Input:
.IP
.nf
\f[C]
<quantity>
<quantityGroup>
<quantityValue quantityUnitOfMeasure=\[dq]cm\[dq]>15</quantityValue>
</quantityGroup>
</quantity>
\f[R]
.fi
.PP
Command:
.IP
.nf
\f[C]
$ s1kd-uom -u cm -t in <DM>
\f[R]
.fi
.PP
Output:
.IP
.nf
\f[C]
<quantity>
<quantityGroup>
<quantityValue quantityUnitOfMeasure=\[dq]in\[dq]>5.91</quantityValue>
</quantityGroup>
</quantity>
\f[R]
.fi
.SS Using a custom formula and format
.PP
Input:
.IP
.nf
\f[C]
<quantity
quantityType=\[dq]qty02\[dq]
quantityTypeSpecifics=\[dq]CAD\[dq]>10.00</quantity>
\f[R]
.fi
.PP
Command:
.IP
.nf
\f[C]
$ s1kd-uom -u CAD -t USD -e \[aq]$value div 1.31\[aq] -F \[aq]0.00\[aq]
\f[R]
.fi
.PP
Output:
.IP
.nf
\f[C]
<quantity
quantityType=\[dq]qty02\[dq]
quantityTypeSpecifics=\[dq]USD\[dq]>7.36</quantity>
\f[R]
.fi
.SH UOM FILE SCHEMA
.SS UOM
.PP
\f[I]Markup element:\f[R] \f[C]<uom>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]format\f[R] (O), the number format for all rules.
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<convert>\f[R]
.SS Conversion rule
.PP
The element \f[C]<convert>\f[R] defines a rule to convert one unit of
measure to another.
.PP
\f[I]Markup element:\f[R] \f[C]<convert>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]format\f[R] (O), the number format for this specific rule.
.IP \[bu] 2
\f[C]formula\f[R] (M), the expression used to convert the quantity
value.
.IP \[bu] 2
\f[C]from\f[R] (M), unit of measure to convert from.
.IP \[bu] 2
\f[C]to\f[R] (M), unit of measure to convert to.
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
None
.SH UOMDISPLAY FILE SCHEMA
.SS UOM display
.PP
\f[I]Markup element:\f[R] \f[C]<uomDisplay>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<format>\f[R]
.IP \[bu] 2
\f[C]<groupTypePrefixes>\f[R]
.IP \[bu] 2
\f[C]<wrapInto>\f[R]
.IP \[bu] 2
\f[C]<uoms>\f[R]
.IP \[bu] 2
\f[C]<currencies>\f[R]
.SS Quantity value format
.PP
\f[I]Markup element:\f[R] \f[C]<format>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]name\f[R] (M), the name of the format
.IP \[bu] 2
\f[C]decimalSeparator\f[R] (M), the decimal separator
.IP \[bu] 2
\f[C]groupingSeparator\f[R] (M), the grouping separator
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
None
.SS Group type prefixes
.PP
The element \f[C]<groupTypePrefixes>\f[R] specifies prefixes which are
added for specific group types.
.PP
\f[I]Markup element:\f[R] \f[C]<groupTypePrefixes>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<nominal>\f[R], text placed before a nominal group.
.IP \[bu] 2
\f[C]<minimum>\f[R], text placed before a minimum group.
.IP \[bu] 2
\f[C]<minimumRange>\f[R], text placed before a minimum group that is
followed by a maximum group to specify a range.
.IP \[bu] 2
\f[C]<maximum>\f[R], text placed before a maximum group.
.IP \[bu] 2
\f[C]<maximumRange>\f[R], text placed before a maximum group that is
preceded by a minimum group to specify a range.
.SS Wrap into element
.PP
\f[I]Markup element:\f[R] \f[C]<wrapInto>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.PP
The element \f[C]<wrapInto>\f[R] contains one child element of any type,
which quantities will be wrapped in to after formatting.
.SS Units of measure
.PP
\f[I]Markup element:\f[R] \f[C]<uoms>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<uom>\f[R]
.PP
The element \f[C]<uoms>\f[R] may also contain arbitrary XSLT elements
which will be processed for all units of measure.
.SS Display of a unit of measure
.PP
\f[I]Markup element:\f[R] \f[C]<uom>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]name\f[R] (M), the name of the UOM.
.PP
\f[I]Child elements:\f[R]
.PP
The element \f[C]<uom>\f[R] may contain mixed content, which will be
used for the display of the unit of measure.
This can include XSLT elements, which allows for handling complex cases
of UOM display, such as pluralization.
.SS Currencies
.PP
\f[I]Markup element:\f[R] \f[C]<currencies>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
None
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<currency>\f[R]
.PP
The element \f[C]<currencies>\f[R] may also contain arbitrary XSLT
elements which will be processed for all currencies.
.SS Display of a currency
.PP
\f[I]Markup element:\f[R] \f[C]<currency>\f[R]
.PP
\f[I]Attributes:\f[R]
.IP \[bu] 2
\f[C]name\f[R] (M), the name of the currency.
.PP
\f[I]Child elements:\f[R]
.IP \[bu] 2
\f[C]<prefix>\f[R], text placed before the currency value.
.IP \[bu] 2
\f[C]<postfix>\f[R], text placed after the currency value.
.PP
The child elements of \f[C]<currency>\f[R] may contain mixed content,
which will be used for the display of the unit of measure.
This can include XSLT elements, which allows for handling complex cases
of currency display.
.SH AUTHORS
khzae.net.