summaryrefslogtreecommitdiff
path: root/macros/generic/texdimens/texdimens.md
diff options
context:
space:
mode:
Diffstat (limited to 'macros/generic/texdimens/texdimens.md')
-rw-r--r--macros/generic/texdimens/texdimens.md189
1 files changed, 127 insertions, 62 deletions
diff --git a/macros/generic/texdimens/texdimens.md b/macros/generic/texdimens/texdimens.md
index ec6ac406e0..ed0994f406 100644
--- a/macros/generic/texdimens/texdimens.md
+++ b/macros/generic/texdimens/texdimens.md
@@ -1,16 +1,13 @@
-texdimens
-=========
+% texdimens 1.1
+% Jean-François Burnol
+% 2021/11/17
## Copyright and License
Copyright (c) 2021 Jean-François Burnol
-This file is part of the texdimens package distributed under the
-LPPL 1.3c. See file LICENSE.md.
-
-Repository: https://github.com/jfbu/texdimens
-
-Release: `1.0 2021/11/10`
+The texdimens [CTAN package](https://ctan.org/pkg/texdimens) is
+distributed under the [LPPL 1.3c](https://ctan.org/license/lppl1.3c).
## Usage
@@ -20,6 +17,9 @@ Utilities and documentation related to TeX dimensional units, usable:
- with LaTeX: `\usepackage{texdimens}`
+For reporting issues, use the
+[package repository](https://github.com/jfbu/texdimens).
+
## Aim of this package
The aim of this package is to provide facilities to express dimensions
@@ -39,8 +39,8 @@ This package provides expandable macros:
`\texdimenbp` takes on input some dimension or dimension expression and
produces on output a decimal `D` such that `D bp` is guaranteed to be
-the same dimension as the input, *if* it admits any representation as `E
-bp`; else it will be either the closest match from above or from
+the same dimension as the input, *if* it admits any representation as `E bp`;
+else it will be either the closest match from above or from
below. For this unit, as well as for `nd` and `dd` the difference is at
most `1sp`. For other units (not `pt` of course) the distance will
usually be larger than `1sp` and one does not know if the approximant
@@ -71,13 +71,6 @@ details in the complete macro description.
## Quick review of basics: TeX points and scaled points
-This project requires the e-TeX extensions `\dimexpr` and `\numexpr`.
-The notation `<dim. expr.>` in the macro descriptions refers to a
-*dimensional expression* as accepted by `\dimexpr`. The syntax has some
-peculiarities: among them the fact that `-(...)` (for example `-(3pt)`)
-is illegal, one must use alternatives such as `0pt-(...)` or a
-sub-expression `-\dimexpr...\relax` for example.
-
TeX dimensions are represented internally by a signed integer which is
in absolute value at most `0x3FFFFFFF`, i.e. `1073741823`. The
corresponding unit is called the "scaled point", i.e. `1sp` is `1/65536`
@@ -237,11 +230,21 @@ the `pt`.
## Macros of this package (full list)
-The macros are all expandable, and most are f-expandable (check the
-source code). They parse their arguments via `\dimexpr` so can be nested
+This project requires the `\dimexpr`, `\numexpr` e-TeX extensions. It
+also requires the `\expanded` primitive (available in all engines since
+TeXLive 2019).
+
+The macros provided by the package are all expandable, even
+f-expandable. They parse their arguments via `\dimexpr` so can be nested
(with appropriate units added, as the outputs always are bare decimal
numbers).
+The notation `<dim. expr.>` in the macro descriptions refers to a
+*dimensional expression* as accepted by `\dimexpr`. The syntax has some
+peculiarities: among them the fact that `-(...)` (for example `-(3pt)`)
+is illegal, one must use alternatives such as `0pt-(...)` or a
+sub-expression `-\dimexpr...\relax` for example.
+
Negative dimensions behave as if replaced by their absolute value, then
at last step the sign (if result is not zero) is applied (so "down" means
"towards zero", and "up" means "away from zero").
@@ -274,11 +277,11 @@ Remarks about "Dimension too large" issues:
particular `\maxdimen`, and the output `F` will always be such that
TeX parses `F<D2pt>` into exactly the same dimension as `D1pt`.
-`\texdimenpt{<dim. expr.>}`
+### `\texdimenpt{<dim. expr.>}`
> Does `\the\dimexpr <dim. expr.> \relax` then removes the `pt`.
-`\texdimenbp{<dim. expr.>}`
+### `\texdimenbp{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dbp`
> represents the dimension exactly if possible. If not possible it
@@ -288,19 +291,19 @@ Remarks about "Dimension too large" issues:
> `\maxdimen` on input produces `16322.78954` and indeed is realized as
> `16322.78954bp`.
-`\texdimenbpdown{<dim. expr.>}`
+### `\texdimenbpdown{<dim. expr.>}`
> 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.
-`\texdimenbpup{<dim. expr.>}`
+### `\texdimenbpup{<dim. expr.>}`
> 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.
-`\texdimennd{<dim. expr.>}`
+### `\texdimennd{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dnd`
> represents the dimension exactly if possible. If not possible it
@@ -310,19 +313,19 @@ Remarks about "Dimension too large" issues:
> `\maxdimen` on input produces `15355.51532` and indeed is realized as
> `15355.51532nd`.
-`\texdimennddown{<dim. expr.>}`
+### `\texdimennddown{<dim. expr.>}`
> 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.
-`\texdimenndup{<dim. expr.>}`
+### `\texdimenndup{<dim. expr.>}`
> 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.
-`\texdimendd{<dim. expr.>}`
+### `\texdimendd{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Ddd`
> represents the dimension exactly if possible. If not possible it
@@ -334,13 +337,13 @@ Remarks about "Dimension too large" issues:
> `\maxdimen-1sp` is the maximal input for which the output remains
> less than `\maxdimen` (max attainable dimension: `\maxdimen-1sp`).
-`\texdimendddown{<dim. expr.>}`
+### `\texdimendddown{<dim. expr.>}`
> 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.
-`\texdimenddup{<dim. expr.>}`
+### `\texdimenddup{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Ddd`
> represents the dimension exactly if possible. If not possible it
@@ -349,7 +352,7 @@ Remarks about "Dimension too large" issues:
> If input is `\maxdimen`, then `Ddd` virtually represents
> `\maxdimen+1sp` and will trigger on use "Dimension too large".
-`\texdimenmm{<dim. expr.>}`
+### `\texdimenmm{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dmm`
> represents the dimension exactly if possible. If not possible it
@@ -360,13 +363,13 @@ Remarks about "Dimension too large" issues:
> `\maxdimen` as input produces on output `5758.31741` and indeed the
> maximal attainable dimension is `5758.31741mm` (`\maxdimen-1sp`).
-`\texdimenmmdown{<dim. expr.>}`
+### `\texdimenmmdown{<dim. expr.>}`
> 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.
-`\texdimenmmup{<dim. expr.>}`
+### `\texdimenmmup{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dmm`
> represents the dimension exactly if possible. If not possible it
@@ -375,7 +378,7 @@ Remarks about "Dimension too large" issues:
> If input is `\maxdimen`, then `Dmm` virtually represents
> `\maxdimen+2sp` and will trigger on use "Dimension too large".
-`\texdimenpc{<dim. expr.>}`
+### `\texdimenpc{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dpc`
> represents the dimension exactly if possible. If not possible it
@@ -385,13 +388,13 @@ Remarks about "Dimension too large" issues:
> `\maxdimen` as input produces on output `1365.33333` and indeed the
> maximal attainable dimension is `1365.33333pc` (`\maxdimen-3sp`).
-`\texdimenpcdown{<dim. expr.>}`
+### `\texdimenpcdown{<dim. expr.>}`
> 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.
-`\texdimenpcup{<dim. expr.>}`
+### `\texdimenpcup{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dpc`
> represents the dimension exactly if possible. If not possible it
@@ -400,7 +403,7 @@ Remarks about "Dimension too large" issues:
> If input is `>\maxdimen-3sp`, then `Dpc` virtually represents
> `\maxdimen+9sp` and will trigger on use "Dimension too large".
-`\texdimennc{<dim. expr.>}`
+### `\texdimennc{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dnc`
> represents the dimension exactly if possible. If not possible it
@@ -413,13 +416,13 @@ Remarks about "Dimension too large" issues:
> `\maxdimen-2sp` is the maximal input for which the output remains
> less than `\maxdimen` (max attainable dimension: `\maxdimen-9sp`).
-`\texdimenncdown{<dim. expr.>}`
+### `\texdimenncdown{<dim. expr.>}`
> 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.
-`\texdimenncup{<dim. expr.>}`
+### `\texdimenncup{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dnc`
> represents the dimension exactly if possible. If not possible it
@@ -428,7 +431,7 @@ Remarks about "Dimension too large" issues:
> If input is `>\maxdimen-9sp`, then `Dnc` virtually represents
> `\maxdimen+4sp` and will trigger on use "Dimension too large".
-`\texdimencc{<dim. expr.>}`
+### `\texdimencc{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dcc`
> represents the dimension exactly if possible. If not possible it
@@ -439,13 +442,13 @@ Remarks about "Dimension too large" issues:
> `\maxdimen` as input produces on output `1276.00215` and indeed the
> maximal attainable dimension is `1276.00215cc` (`\maxdimen-2sp`).
-`\texdimenccdown{<dim. expr.>}`
+### `\texdimenccdown{<dim. expr.>}`
> 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.
-`\texdimenccup{<dim. expr.>}`
+### `\texdimenccup{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dcc`
> represents the dimension exactly if possible. If not possible it
@@ -454,7 +457,7 @@ Remarks about "Dimension too large" issues:
> If input is `>\maxdimen-2sp`, then `Dcc` virtually represents
> `\maxdimen+11sp` and will trigger on use "Dimension too large".
-`\texdimencm{<dim. expr.>}`
+### `\texdimencm{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dcm`
> represents the dimension exactly if possible. If not possible it
@@ -465,13 +468,13 @@ Remarks about "Dimension too large" issues:
> `\maxdimen` as input produces on output `575.83174` and indeed the
> maximal attainable dimension is `575.83174cm` (`\maxdimen-1sp`).
-`\texdimencmdown{<dim. expr.>}`
+### `\texdimencmdown{<dim. expr.>}`
> 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.
-`\texdimencmup{<dim. expr.>}`
+### `\texdimencmup{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Dcm`
> represents the dimension exactly if possible. If not possible it
@@ -480,7 +483,7 @@ Remarks about "Dimension too large" issues:
> If input is `\maxdimen`, then `Dcm` virtually represents
> `\maxdimen+28sp` and will trigger on use "Dimension too large".
-`\texdimenin{<dim. expr.>}`
+### `\texdimenin{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Din`
> represents the dimension exactly if possible. If not possible it
@@ -493,13 +496,13 @@ Remarks about "Dimension too large" issues:
> `\maxdimen-19sp` is the maximal input for which the output remains
> less than `\maxdimen` (max attainable dimension: `\maxdimen-55sp`).
-`\texdimenindown{<dim. expr.>}`
+### `\texdimenindown{<dim. expr.>}`
> 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.
-`\texdimeninup{<dim. expr.>}`
+### `\texdimeninup{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that `Din`
> represents the dimension exactly if possible. If not possible it
@@ -508,14 +511,14 @@ Remarks about "Dimension too large" issues:
> If input is `>\maxdimen-55sp`, then `Din` virtually represents
> `\maxdimen+17sp` and will trigger on use "Dimension too large".
-`\texdimenbothcmin{<dim. expr.>}`
+### `\texdimenbothcmin{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that
> `Din` is the largest dimension not exceeding the original one (in
> absolute value) and exactly representable both in the `in` and `cm`
> units.
-`\texdimenbothincm{<dim. expr.>}`
+### `\texdimenbothincm{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that
> `Dcm` is the largest dimension not exceeding the original one (in
@@ -523,7 +526,7 @@ Remarks about "Dimension too large" issues:
> units. Thus both expressions `\texdimenbothcmin{<dim. expr.>}in` and
> `\texdimenbothincm{<dim. expr.>}cm` represent the same dimension.
-`\texdimenbothcminpt{<dim. expr.>}`
+### `\texdimenbothcminpt{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that
> `Dpt` is the largest dimension not exceeding the original one (in
@@ -531,28 +534,28 @@ Remarks about "Dimension too large" issues:
> units. It thus represents the same dimension as the one determined by
> `\texdimenbothcmin` and `\texdimenbothincm`.
-`\texdimenbothincmpt{<dim. expr.>}`
+### `\texdimenbothincmpt{<dim. expr.>}`
> Alias for `\texdimenbothcminpt`.
-`\texdimenbothcminsp{<dim. expr.>}`
+### `\texdimenbothcminsp{<dim. expr.>}`
> Produces an integer (explicit digit tokens) `N` such that `Nsp` is the
> largest dimension not exceeding the original one in absolute value and
> exactly representable both in the `in` and `cm` units.
-`\texdimenbothincmsp{<dim. expr.>}`
+### `\texdimenbothincmsp{<dim. expr.>}`
> Alias for `\texdimenbothcminsp`.
-`\texdimenbothbpmm{<dim. expr.>}`
+### `\texdimenbothbpmm{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that
> `Dmm` is the largest dimension smaller (in absolute value) than the
> original one and exactly representable both in the `bp` and `mm`
> units.
-`\texdimenbothmmbp{<dim. expr.>}`
+### `\texdimenbothmmbp{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that
> `Dbp` is the largest dimension smaller (in absolute value) than the
@@ -560,27 +563,27 @@ Remarks about "Dimension too large" issues:
> units. Thus `\texdimenbothmmbp{<dim. expr.>}bp` is the same
> dimension as `\texdimenbothbpmm{<dim. expr.>}mm`.
-`\texdimenbothbpmmpt{<dim. expr.>}`
+### `\texdimenbothbpmmpt{<dim. expr.>}`
> Produces a decimal (with up to five decimal places) `D` such that
> `Dpt` is the largest dimension not exceeding the original one and
> exactly representable both in the `bp` and `mm` units.
-`\texdimenbothmmbppt{<dim. expr.>}`
+### `\texdimenbothmmbppt{<dim. expr.>}`
> Alias for `\texdimenbothbpmmpt`.
-`\texdimenbothbpmmsp{<dim. expr.>}`
+### `\texdimenbothbpmmsp{<dim. expr.>}`
> Produces an integer (explicit digit tokens) `N` such that `Nsp`
> is the largest dimension not exceeding the original one and
> exactly representable both in the `bp` and `mm` units.
-`\texdimenbothmmbpsp{<dim. expr.>}`
+### `\texdimenbothmmbpsp{<dim. expr.>}`
> Alias for `\texdimenbothbpmmsp`.
-`\texdimenwithunit{<dim. expr. 1>}{<dim expr. 2>}`
+### `\texdimenwithunit{<dim. expr. 1>}{<dim expr. 2>}`
> Produces a decimal `D` such that `D\dimexpr <dim expr. 2>\relax` is
> considered by TeX the same as `<dim. expr. 1>` if at all possible. If
@@ -592,8 +595,8 @@ Remarks about "Dimension too large" issues:
> direction would have given a better or worst match.
>
> `\texdimenwithunit{<dim>}{1bp}` and `\texdimenbp{<dim>}` are not
-> the same: The former produces a decimal `D` such that `D\dimexpr
-> 1bp\relax` is represented internally as is `<dim>` if at all possible,
+> the same: The former produces a decimal `D` such that `D\dimexpr 1bp\relax`
+> is represented internally as is `<dim>` if at all possible,
> whereas the latter produces a decimal `D` such that `D bp` is the one
> aiming at being the same as `<dim>`. Using `D\dimexpr 1bp\relax` implies
> a conversion factor equal to `65781/65536`, whereas `D bp` involves
@@ -618,6 +621,68 @@ Remarks about "Dimension too large" issues:
> bias to be "shifted upwards" (in its last decimal place) compared to
> the (rounded) value `D1/D2` or rather `N1/N2` still stands.
+## Change log
+
+### [1.1 (2021/11/17)](https://github.com/jfbu/texdimens/compare/1.0...1.1#files_bucket)
+
+- internal refactorings across the entire code base aiming at (small)
+ efficiency gains from optimized TeX token manipulations
+- in particular, the algorithm for `\texdimenwithunit{<dim1>}{<dim2>}`
+ in the "`dim2<1pt`" branch got modified (output unchanged)
+- all macros now f-expandable (this was already the case at `1.0` except
+ for `\texdimenwithunit` with arguments of opposite signs, the
+ second one not exceeding `1pt` in absolute value)
+- the `\expanded` primitive is required (present in all engines since
+ TeXLive 2019)
+- the usual batch of documentation additions or fix-ups, also in
+ code comments (fix in particular issues #21, #22)
+- addition of this Change log to the pdf documentation
+- addition of the highlighted commented source code to the pdf documentation
+
+### [1.0 (2021/11/10)](https://github.com/jfbu/texdimens/compare/0.99d...1.0#files_bucket)
+
+- new: `\texdimenbothbpmm` and relatives (feature request #10)
+- breaking: `\texdimenwithunit` output for second argument `<1pt` still
+ obeys specs but is closer to mathematical ratio (feature request #16)
+- enhanced: all `up/down` macros (i.e. also for the `dd`, `nc`, `in`
+ units) accept the full range of dimensions (feature request #18)
+- enhanced: `\texdimenwithunit`'s second argument is now allowed
+ to be negative (feature request #13)
+
+### [0.99a-d (2021/11/04)](https://github.com/jfbu/texdimens/compare/0.99...0.99d#files_bucket)
+
+- documentation in TeX/LaTeX installations available in pdf format
+- the usual batch of documentation additions or fix-ups
+- let the CTAN `README.md` be much shortened, and provide `texdimens.md`
+ as the one matching the repo `README.md`
+- fix bugs of `\texdimenwithunit{<dim1>}{<dime2>}` for `dim1=0pt` or
+ `dim2=1pt` (#3, #4, #6, #8)
+
+### [0.99 (2021/11/02)](https://github.com/jfbu/texdimens/compare/0.9...0.99#files_bucket)
+
+- new: `\texdimenwithunit{<dim1>}{<dim2>}` (feature request #2)
+
+### [0.9 (2021/07/21)](https://github.com/jfbu/texdimens/compare/0.9delta...0.9#files_bucket)
+
+- new: `\texdimenbothincm` and relatives
+- breaking: use `\texdimen` prefix for all macros
+
+### [0.9delta (2021/07/15)](https://github.com/jfbu/texdimens/compare/0.9gamma...0.9delta#files_bucket)
+
+- internal refactorings
+
+### [0.9gamma (2021/07/14)](https://github.com/jfbu/texdimens/compare/0.9beta...0.9gamma#files_bucket)
+
+- new: `\texdiminbpdown` (now `\texdimenbpdown`), `\texdiminbpup`
+ (now `\texdimenbpup`) and similar named macros associated with
+ the other units
+
+### [0.9beta (2021/06/30)](https://github.com/jfbu/texdimens/compare/54f4eb13...0.9beta#files_bucket)
+
+- initial release: provides `\texdiminbp` (now `\texdimenbp`) and
+ similar named macros for the units `nd`, `dd`, `mm`, `pc`, `nc`, `cc`,
+ `cm`, `in`
+
## Acknowledgements