texdimens (21jul21)

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

1 files changed, 138 insertions, 120 deletions

diff --git a/Master/texmf-dist/doc/generic/texdimens/README.md b/Master/texmf-dist/doc/generic/texdimens/README.md
index 4f028fe6895..d574ae2ae68 100644
--- a/Master/texmf-dist/doc/generic/texdimens/README.md
+++ b/Master/texmf-dist/doc/generic/texdimens/README.md
@@ -10,7 +10,7 @@ LPPL 1.3c.  See file LICENSE.md.
 
 Development: https://github.com/jfbu/texdimens
 
-Release: `0.9delta 2021/07/15`
+Release: `0.9 2021/07/21`
 
 ## Aim of this package
 
@@ -46,24 +46,24 @@ of one TeX point `1pt`, or rather `1pt` is represented internally as `65536`.
 
 If `\foo` is a dimen register:
 
-- `\number\foo` produces the integer `N` such as `\foo` is the same as `N sp`,
+- `\number\foo` produces the integer `N` such as `\foo` is the same as `Nsp`,
 
 - inside `\numexpr`, `\foo` is replaced by `N`,
 
 - `\the\foo` produces a decimal `D` (with at most five places) followed
-with `pt` (catcode 12 tokens) and this output `D pt` can serve as input
+with `pt` (catcode 12 tokens) and this output `Dpt` can serve as input
 in a dimen assignment to produce the same dimension as `\foo`.  One can
 also use the catcode 11 characters `pt` for this.  Digits and decimal
 mark must have their standard catcode 12.
 
-When TeX encounters a dimen denotation of the type `D pt` it will
+When TeX encounters a dimen denotation of the type `Dpt` it will
 compute `N` in a way equivalent to `N = round(65536 D)` where ties are
 rounded away from zero.  Only 17 decimal places of `D` are
 kept as it can be shown that going beyond can not change the result.
 
-When `\foo` has been assigned as `D pt`, `\the\foo` will produce some
-`E pt` where `E` is not necessarily the same as `D`.  But it is guaranteed
-that `E pt` defines the same dimension as `D pt̀`.
+When `\foo` has been assigned as `Dpt`, `\the\foo` will produce some
+`Ept` where `E` is not necessarily the same as `D`.  But it is guaranteed
+that `Ept` defines the same dimension as `Dpt̀`.
 
 ## Further units known to TeX on input
 
@@ -100,8 +100,8 @@ among those listed above, it first handles `U` as with the `pt` unit.
 This means that it computes `N = round(65536*U)`. It then multiplies
 this `N` by the conversion factor `phi` and truncates towards zero the
 mathematically exact result to obtain an integer `T`:
-`T=trunc(N*phi)`. The assignment `U uu` is concluded by defining the
-value of the dimension to be `T sp`.
+`T=trunc(N*phi)`. The assignment `Uuu` is concluded by defining the
+value of the dimension to be `Tsp`.
 
 Attention that although the mnemotic is `phi=1uu/1pt`, this formula
 definitely does not apply with numerator and denominator interpreted as
@@ -129,7 +129,7 @@ between attainable dimensions is `72--73sp` for the `in` and `28--29sp`
 for the `cm`, and as `1in` differs internally from `2.54cm` by only
 `12sp` (see below the `xintsession` verbatim) it is impossible to adjust
 either the `in` side or the `cm` side to obtain equality.  See in the
-[TODO] section the closest dimension attainable both via `in` and via
+[Extras?] section the closest dimension attainable both via `in` and via
 `cm`.
 
 In particular `1in==2.54cm` is **false** in TeX, but it is true that
@@ -152,19 +152,19 @@ In particular `1in==2.54cm` is **false** in TeX, but it is true that
 other units the maximal attainable dimensions in `sp` unit are given in
 the middle column of the next table.
 
-    maximal allowed      the corresponding       minimal TeX dimen denotation
-    (with 5 places)   maximal attainable dim.    causing "Dimension too large"
-    ---------------  --------------------------  --------------------------
-    16383.99999 pt   1073741823 sp (=\maxdimen)  16383.99999237060546875 pt
-    16322.78954 bp   1073741823 sp (=\maxdimen)  16322.78954315185546875 bp
-    15355.51532 nd   1073741823 sp (=\maxdimen)  15355.51532745361328125 nd
-    15312.02584 dd   1073741822 sp               15312.02584075927734375 dd
-     5758.31742 mm   1073741822 sp                5758.31742095947265625 mm
-     1365.33333 pc   1073741820 sp                1365.33333587646484375 pc
-     1279.62627 nc   1073741814 sp                1279.62627410888671875 nc
-     1276.00215 cc   1073741821 sp                1276.00215911865234375 cc
-      575.83174 cm   1073741822 sp                 575.83174896240234375 cm
-      226.70540 in   1073741768 sp                 226.70540618896484375 in
+    maximal allowed      the corresponding      minimal TeX dimen denotation
+    (with 5 places)   maximal attainable dim.   causing "Dimension too large"
+    ---------------  -------------------------  --------------------------
+    16383.99999pt    1073741823sp (=\maxdimen)  16383.99999237060546875pt
+    16322.78954bp    1073741823sp (=\maxdimen)  16322.78954315185546875bp
+    15355.51532nd    1073741823sp (=\maxdimen)  15355.51532745361328125nd
+    15312.02584dd    1073741822sp               15312.02584075927734375dd
+     5758.31742mm    1073741822sp                5758.31742095947265625mm
+     1365.33333pc    1073741820sp                1365.33333587646484375pc
+     1279.62627nc    1073741814sp                1279.62627410888671875nc
+     1276.00215cc    1073741821sp                1276.00215911865234375cc
+      575.83174cm    1073741822sp                 575.83174896240234375cm
+      226.70540in    1073741768sp                 226.70540618896484375in
 
 Perhaps for these various peculiarities with dimensional units, TeX does
 not provide an output facility for them similar to what `\the` achieves for
@@ -173,11 +173,11 @@ the `pt`.
 ## Macros of this package
 
 The macros defined by the package are expandable, and will expand
-completely in an `\edef`, or in a `\dimexpr...\relax` construc.
+completely in an `\edef`, or in a `\dimexpr...\relax` construct.
 As they parse their inputs via `\dimexpr` they can be nested (with
-suitable postfix dimension unit added to inner macro).
+the suitable dimension unit added as postfix to nested macro).
 
-Apart for the `\texdimin<uu>up` in case of a negative input, they will
+Apart from the `\texdimen<uu>up` in case of a negative input, they will
 even expand completely under f-expansion.
 
 Negative dimensions behave as if replaced by their absolute value, then
@@ -187,67 +187,67 @@ at last step the sign (if result is not zero) is applied (so "down" means
 1. For input `X` equal to (or sufficiently close to) `\maxdimen` and
    those units `uu` for which `\maxdimen` is not exactly representable
    (i.e. all units except `pt`, `bp` and `nd`), the output `D` of the
-   "up" macros `\texdimin<uu>up{X}`, if used as `Duu` in a dimension
+   "up" macros `\texdimen<uu>up{X}`, if used as `Duu` in a dimension
    assignment or expression, will (naturally) trigger a "Dimension too
    large" error.
 2. For `dd`, `nc` and `in`, and input `X` equal to (or sufficiently
-   close to) `\maxdimen` it turns out that `\texdimin<uu>{X}` produces
+   close to) `\maxdimen` it turns out that `\texdimen<uu>{X}` produces
    an output `D` such that `Duu` is the first "virtually attainable" TeX
    dimension *beyond* `\maxdimen`.  Hence `Duu` will trigger on use
    "Dimension too large error".
 3. Again for the `dd`, `nc` and `in` units, both the "down" and "up" macros
    will trigger "Dimension too large" during their execution if used
-   with an input equal to (or sufficiently close to `\maxdimen`.
+   with an input equal to (or sufficiently close to) `\maxdimen`.
 
-`\texdiminpt{<dim. expr.>}`
+`\texdimenpt{<dim. expr.>}`
 
 > Does `\the\dimexpr <dim. expr.> \relax` then removes the `pt`.
 
-`\texdiminbp{<dim. expr.>}`
+`\texdimenbp{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D bp`
+> Produces a decimal (with up to five decimal places) `D` such that `Dbp`
 > represents the dimension exactly if possible. If not possible it
 > will differ by `1sp` from the original dimension, but it is not
 > known in advance if it will be above or below.
 
 > `\maxdimen` on input produces `16322.78954` and indeed is realized as `16322.78954bp`.
 
-`\texdiminbpdown{<dim. expr.>}`
+`\texdimenbpdown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D bp`
+> Produces a decimal (with up to five decimal places) `D` such that `Dbp`
 > represents the dimension exactly if possible. If not possible it
 > will be smaller by `1sp` from the original dimension.
 
-`\texdiminbpup{<dim. expr.>}`
+`\texdimenbpup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D bp`
+> Produces a decimal (with up to five decimal places) `D` such that `Dbp`
 > represents the dimension exactly if possible. If not possible it
 > will be larger by `1sp` from the original dimension.
 
-`\texdiminnd{<dim. expr.>}`
+`\texdimennd{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D nd`
+> Produces a decimal (with up to five decimal places) `D` such that `Dnd`
 > represents the dimension exactly if possible. If not possible it
 > will differ by `1sp` from the original dimension, but it is not
 > known in advance if it will be above or below.
 
 > `\maxdimen` on input produces `15355.51532` and indeed is realized as `15355.51532nd`.
 
-`\texdiminnddown{<dim. expr.>}`
+`\texdimennddown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D nd`
+> Produces a decimal (with up to five decimal places) `D` such that `Dnd`
 > represents the dimension exactly if possible. If not possible it
 > will be smaller by `1sp` from the original dimension.
 
-`\texdiminndup{<dim. expr.>}`
+`\texdimenndup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D nd`
+> Produces a decimal (with up to five decimal places) `D` such that `Dnd`
 > represents the dimension exactly if possible. If not possible it
 > will be larger by `1sp` from the original dimension.
 
-`\texdimindd{<dim. expr.>}`
+`\texdimendd{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D dd`
+> Produces a decimal (with up to five decimal places) `D` such that `Ddd`
 > represents the dimension exactly if possible. If not possible it
 > will differ by `1sp` from the original dimension, but it is not
 > known in advance if it will be above or below.
@@ -256,21 +256,21 @@ at last step the sign (if result is not zero) is applied (so "down" means
 > will trigger "Dimension too large" error.
 > `\maxdimen-1sp` is attainable via `15312.02584dd`.
 
-`\texdimindddown{<dim. expr.>}`
+`\texdimendddown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D dd`
+> Produces a decimal (with up to five decimal places) `D` such that `Ddd`
 > represents the dimension exactly if possible. If not possible it
 > will be smaller by `1sp` from the original dimension.
 
-`\texdiminddup{<dim. expr.>}`
+`\texdimenddup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D dd`
+> Produces a decimal (with up to five decimal places) `D` such that `Ddd`
 > represents the dimension exactly if possible. If not possible it
 > will be larger by `1sp` from the original dimension.
 
-`\texdiminmm{<dim. expr.>}`
+`\texdimenmm{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D mm`
+> Produces a decimal (with up to five decimal places) `D` such that `Dmm`
 > represents the dimension exactly if possible. If not possible it
 > will either be the closest from below or from above, but it is not
 > known in advance which one (and it is not known if the other choice
@@ -279,21 +279,21 @@ at last step the sign (if result is not zero) is applied (so "down" means
 > `\maxdimen` as input produces on output `5758.31741` and indeed the
 > maximal attainable dimension is `5758.31741mm` (`1073741822sp`).
 
-`\texdiminmmdown{<dim. expr.>}`
+`\texdimenmmdown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D mm`
+> Produces a decimal (with up to five decimal places) `D` such that `Dmm`
 > represents the dimension exactly if possible. If not possible it
 > will be largest representable dimension smaller than the original one.
 
-`\texdiminmmup{<dim. expr.>}`
+`\texdimenmmup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D mm`
+> Produces a decimal (with up to five decimal places) `D` such that `Dmm`
 > represents the dimension exactly if possible. If not possible it
 > will be smallest representable dimension larger than the original one.
 
-`\texdiminpc{<dim. expr.>}`
+`\texdimenpc{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D pc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dpc`
 > represents the dimension exactly if possible. If not possible it
 > will be the closest representable one (in case of tie, the approximant
 > from above is chosen).
@@ -301,21 +301,21 @@ at last step the sign (if result is not zero) is applied (so "down" means
 > `\maxdimen` as input produces on output `1365.33333` and indeed the
 > maximal attainable dimension is `1365.33333pc` (`1073741820sp`).
 
-`\texdiminpcdown{<dim. expr.>}`
+`\texdimenpcdown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D pc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dpc`
 > represents the dimension exactly if possible. If not possible it
 > will be largest representable dimension smaller than the original one.
 
-`\texdiminpcup{<dim. expr.>}`
+`\texdimenpcup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D pc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dpc`
 > represents the dimension exactly if possible. If not possible it
 > will be smallest representable dimension larger than the original one.
 
-`\texdiminnc{<dim. expr.>}`
+`\texdimennc{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D nc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dnc`
 > represents the dimension exactly if possible. If not possible it
 > will either be the closest from below or from above, but it is not
 > known in advance which one (and it is not known if the other choice
@@ -325,21 +325,21 @@ at last step the sign (if result is not zero) is applied (so "down" means
 > will trigger "Dimension too large" error.
 > `\maxdimen-9sp` is attainable via `1279.62627nc`.
 
-`\texdiminncdown{<dim. expr.>}`
+`\texdimenncdown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D nc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dnc`
 > represents the dimension exactly if possible. If not possible it
 > will be largest representable dimension smaller than the original one.
 
-`\texdiminncup{<dim. expr.>}`
+`\texdimenncup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D nc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dnc`
 > represents the dimension exactly if possible. If not possible it
 > will be smallest representable dimension larger than the original one.
 
-`\texdimincc{<dim. expr.>}`
+`\texdimencc{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D cc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dcc`
 > represents the dimension exactly if possible. If not possible it
 > will either be the closest from below or from above, but it is not
 > known in advance which one (and it is not known if the other choice
@@ -348,21 +348,21 @@ at last step the sign (if result is not zero) is applied (so "down" means
 > `\maxdimen` as input produces on output `1276.00215` and indeed the
 > maximal attainable dimension is `1276.00215cc` (`1073741821sp`).
 
-`\texdiminccdown{<dim. expr.>}`
+`\texdimenccdown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D cc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dcc`
 > represents the dimension exactly if possible. If not possible it
 > will be largest representable dimension smaller than the original one.
 
-`\texdiminccup{<dim. expr.>}`
+`\texdimenccup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D cc`
+> Produces a decimal (with up to five decimal places) `D` such that `Dcc`
 > represents the dimension exactly if possible. If not possible it
 > will be smallest representable dimension larger than the original one.
 
-`\texdimincm{<dim. expr.>}`
+`\texdimencm{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D cm`
+> Produces a decimal (with up to five decimal places) `D` such that `Dcm`
 > represents the dimension exactly if possible. If not possible it
 > will either be the closest from below or from above, but it is not
 > known in advance which one (and it is not known if the other choice
@@ -371,21 +371,21 @@ at last step the sign (if result is not zero) is applied (so "down" means
 > `\maxdimen` as input produces on output `575.83174` and indeed the
 > maximal attainable dimension is `575.83174cm` (`1073741822sp`).
 
-`\texdimincmdown{<dim. expr.>}`
+`\texdimencmdown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D cm`
+> Produces a decimal (with up to five decimal places) `D` such that `Dcm`
 > represents the dimension exactly if possible. If not possible it
 > will be largest representable dimension smaller than the original one.
 
-`\texdimincmup{<dim. expr.>}`
+`\texdimencmup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D cm`
+> Produces a decimal (with up to five decimal places) `D` such that `Dcm`
 > represents the dimension exactly if possible. If not possible it
 > will be smallest representable dimension larger than the original one.
 
-`\texdiminin{<dim. expr.>}`
+`\texdimenin{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D in`
+> Produces a decimal (with up to five decimal places) `D` such that `Din`
 > represents the dimension exactly if possible. If not possible it
 > will either be the closest from below or from above, but it is not
 > known in advance which one (and it is not known if the other choice
@@ -395,18 +395,54 @@ at last step the sign (if result is not zero) is applied (so "down" means
 > will trigger "Dimension too large" error.
 > `\maxdimen-55sp` is maximal attainable dimension (via `226.7054in`).
 
-`\texdiminindown{<dim. expr.>}`
+`\texdimenindown{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D in`
+> Produces a decimal (with up to five decimal places) `D` such that `Din`
 > represents the dimension exactly if possible. If not possible it
 > will be largest representable dimension smaller than the original one.
 
-`\texdimininup{<dim. expr.>}`
+`\texdimeninup{<dim. expr.>}`
 
-> Produces a decimal (with up to five decimal places) `D` such that `D in`
+> Produces a decimal (with up to five decimal places) `D` such that `Din`
 > represents the dimension exactly if possible. If not possible it
 > will be smallest representable dimension larger than the original one.
 
+`\texdimenbothcmin{<dim. expr.>}` (new with `0.9dev`)
+
+> Produces a decimal (with up to five decimal places) `D` such that `Din`
+> is the largest dimension smaller than the original one and
+> exactly representable both in the `in` and `cm` units.
+
+`\texdimenbothincm{<dim. expr.>}` (new with `0.9dev`)
+
+> Produces a decimal (with up to five decimal places) `D` such that `Dcm`
+> is the largest dimension smaller than the original one and
+> exactly representable both in the `in` and `cm` units.  It thus represents
+> the same dimension as `\texdimenbothcmin{<dim. expr.>}in`.
+
+`\texdimenbothcminpt{<dim. expr.>}` (new with `0.9dev`)
+
+> Produces a decimal (with up to five decimal places) `D` such that `Dpt`
+> is the largest dimension smaller than the original one and
+> exactly representable both in the `in` and `cm` units.  It thus represents
+> the same dimension as the one provided by `\texdimenbothcmin` and
+> `\texdimenbothincm`.
+
+`\texdimenbothincmpt{<dim. expr.>}` (new with `0.9dev`)
+
+> Same as `\texdimenbothcminpt`.
+
+`\texdimenbothcminsp{<dim. expr.>}` (new with `0.9dev`)
+
+> Produces an integer (explicit digit tokens) `N` such that `Nsp`
+> is the largest dimension smaller than the original one and
+> exactly representable both in the `in` and `cm` units.
+
+`\texdimenbothincmsp{<dim. expr.>}` (new with `0.9dev`)
+
+> Same as `\texdimenbothcminsp`.
+
+
 ## Extras?
 
 As already stated the "up" and also the "down" macros for the `dd`, `nc`
@@ -418,46 +454,28 @@ some demand for it.
 
 But of course anyhow the output from the "up" macros if used
 as input with the corresponding unit will be beyond `\maxdimen` if the
-latter is not atteignable, i.e. for all units except `bp`, and `nd`
+latter is not attainable, i.e. for all units except `bp`, and `nd`
 (and `pt` but there is no "up" macro for it).
 
-Provide a macro `\texdimforbothincm{<dim.expr.>}` which would output
-the nearest dimension simultaneously representable both in `in` and in
-`cm`?
-
 According to a reference on the web by an anonymous contributor the
 dimensions representable with both `in` and `cm` units have the shape
-`trunc(3613.5*k) sp` for some integer `k`. So we basically may have a
-delta up to about `1800sp` which is about `0.0275pt` and is still small
-(less than one hundredth of a millimeter, i.e. less than ten micron),
-so perhaps such a utility for
-"safe dimensions" may be useful.  Here are for example the dimensions
-nearest to `1in` and realizable both in `in` and `cm` units:
-
-    >>> \input texdimens.tex\relax
-    (executing \input texdimens.tex\relax  in background)
-    (./texdimens.tex) 
-    >>> &exact
-    exact mode (floating point evaluations use 16 digits)
-    >>> (\texdiminin{4737298sp});
-    @_10    1.00021
-    >>> (\texdimincm{4737298sp});
-    @_11    2.54054
-    >>> (\dimexpr1.00021in, \dimexpr2.54054cm);
-    @_12    4737298, 4737298
-    >>> (\texdiminin{4733685sp});
-    @_13    0.99945
-    >>> (\texdimincm{4733685sp});
-    @_14    2.5386
-    >>> (\dimexpr0.99945in, \dimexpr2.5386cm);
-    @_15    4733685, 4733685
-
-As promised, one of them, the upper approximation, is at less than
-one hundredth of millimeter from the two nearby targets.
-
-Simpler however and more efficient
-would be for people to finally adopt the French revolution Système
-Métrique (rather than setting up giant financial paradises).
+`trunc(3613.5*k)sp` for some integer `k`. The largest one smaller
+than a given dimension will thus differ from it by at most about `0.055pt`,
+which is also about `0.02mm`.
+
+For example `\texdimenbothincm{1cm}` expands to `0.99994cm` which maps
+internally to `1864566sp` which differs from TeX's `1cm` by only
+`-113sp`. It can be obtained from `0.39368in` or `28.45102pt`.
+
+And `\texdimenbothcmin{1in}` expands to `0.99945in`, maps internally to
+`4733685sp` which differs from TeX's `1in` by `-2601sp`. It can be obtained
+as `2.5386cm` or `72.2303pt`.
+
+Currently the package does not provide analogous approximations from above.
+For the `1in` for example it would be `4737298sp`, i.e. `1.00021in` which
+differs from TeX's `1in` by `+1012sp` and is obtained also as `2.54054cm`
+and `72.28543pt`.
+
 
 <!--
 -->