summaryrefslogtreecommitdiff
path: root/macros/generic/texdimens/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/texdimens/README.md')
-rw-r--r--macros/generic/texdimens/README.md258
1 files changed, 138 insertions, 120 deletions
diff --git a/macros/generic/texdimens/README.md b/macros/generic/texdimens/README.md
index 4f028fe689..d574ae2ae6 100644
--- a/macros/generic/texdimens/README.md
+++ b/macros/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`.
+
<!--
-->