[latex3-commits] [git/LaTeX3-latex3-latex3] main: Update primitive requirements docs (df25bca58)

[Joseph Wright]

Repository : https://github.com/latex3/latex3
On branch  : main
Link       : https://github.com/latex3/latex3/commit/df25bca58f3e55752fd163b7b9771a64ccd042e6

>---------------------------------------------------------------

commit df25bca58f3e55752fd163b7b9771a64ccd042e6
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Mon Feb 21 07:25:32 2022 +0000

    Update primitive requirements docs
    
    This is now aligned with LaTeX News 31, except that
    \expanded is not absolutely required. I have marked
    that as changing for TL'22: to discuss further.


>---------------------------------------------------------------

df25bca58f3e55752fd163b7b9771a64ccd042e6
 l3kernel/README.md | 64 ++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 48 insertions(+), 16 deletions(-)

diff --git a/l3kernel/README.md b/l3kernel/README.md
index aa111a2d9..358954d57 100644
--- a/l3kernel/README.md
+++ b/l3kernel/README.md
@@ -27,22 +27,54 @@ or modification of functions are made on the list.
 Requirements
 ------------
 
-The `l3kernel` bundle requires the e-TeX extensions and additional functionality
-to support string comparisons, expandable character generation with arbitrary
-category codes (for Unicode engines) and PDF support primitives (where direct
-PDF generation is used). The bundle only works with the following engines:
-* pdfTeX v1.40 or later
-* XeTeX v0.99992 or later
-* LuaTeX v1.10 or later
-* e-(u)pTeX from mid-2012 onward
-
-pdfTeX v1.40 was released in 2007, and so any recent TeX distribution
-supports `l3kernel`. Both XeTeX and LuaTeX have developed more
-actively over the past few years, and for this reason only recent
-releases of these engines are supported.
-
-(Engine developers should contact the team for detailed discussion about
-primitive requirements.)
+The `l3kernel` bundle requires the e-TeX extensions and a number of additional
+'utility' primitives, almost all of which were first added to pdfTeX. In
+particular, the functionality equivalent to the following pdfTeX primitives must
+be available
+
+- `\ifpdfprimitive`
+- `\pdfcreationdate`
+- `\pdfelapsedtime`
+- `\pdffiledump`
+- `\pdffilemoddate`
+- `\pdffilesize`
+- `\pdflastxpos`
+- `\pdflastypos`
+- `\pdfmdfivesum`
+- `\pdfnormaldeviate`
+- `\pdfpageheight`
+- `\pdfpagewidth`
+- `\pdfprimitive`
+- `\pdfrandomseed`
+- `\pdfresettimer`
+- `\pdfsavepos`
+- `\pdfsetrandomseed`
+- `\pdfshellescape`
+- `\pdfstrcmp`
+- `\pdfuniformdeviate`
+
+For ease of reference, these primitives will be referred to as the 'pdfTeX
+utilities'. With the exception of `\expanded`, these have been present in pdfTeX
+since the release of version 1.40.0 in 2007; `\expanded` was added for TeX Live
+2019. Similarly, the full set of these utility primitives has been available in
+XeTeX from the 2019 TeX Live release, and has always been available in LuaTeX
+(some by Lua emulation). The Japanese pTeX and upTeX gained all of the above
+(except `\ifincsname`) for TeX Live 2019 `\ifincsnme` for TeX Live 2020.
+
+At present, the `\expanded` primitive is emulated if unavailable. This code is
+slow and imposes some coding restrictions. As such, it will be *removed* for TeX
+Live 2022
+
+In addition to the above, engines which are fully Unicode-compatible
+must provde the functionality of the following primitives, documented in the
+LuaTeX manual
+
+- `\Uchar`
+- `\Ucharcat`
+- `\Umathcode`
+
+The existence of the primitive `\Umathcode` is used as the marker for Unicode
+support.
 
 Discussion
 ----------