summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/l3kernel/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/l3kernel/README.md')
-rw-r--r--Master/texmf-dist/doc/latex/l3kernel/README.md85
1 files changed, 59 insertions, 26 deletions
diff --git a/Master/texmf-dist/doc/latex/l3kernel/README.md b/Master/texmf-dist/doc/latex/l3kernel/README.md
index aa111a2d92f..cbfdd98c3a9 100644
--- a/Master/texmf-dist/doc/latex/l3kernel/README.md
+++ b/Master/texmf-dist/doc/latex/l3kernel/README.md
@@ -1,24 +1,25 @@
LaTeX3 Programming Conventions
==============================
-Release 2022-02-05
+Release 2022-02-21
Overview
--------
-The files of the `l3kernel` bundle provide a low-level API for TeX programmers
-with special syntax conventions, completely separating it from document level
+The files of the `l3kernel` bundle provide an API for TeX programmers
+with defined syntax conventions, completely separating it from document level
syntax. Hence, the commands provided are not intended for use at the document
level nor for use in describing design layouts in document class files.
-This API provides the foundation on which the LaTeX3 kernel and other advanced
-extensions are built. Special care has been taken so that they can be used
-within a LaTeX2e context as regular packages.
+This API provides the foundation on which new additions to the LaTeX kernel and
+other advanced extensions are built. The programming layer is designed to be
+loaded as part of LaTeX2e format building or as a loaded package with plain TeX
+or other formats.
-While `l3kernel` is still experimental, the bundle is now regarded as broadly
-stable. The syntax conventions and functions provided are now ready for wider
-use. There may still be changes to some functions, but these will be minor when
-compared to the scope of `l3kernel`.
+The syntax and functionality provided by `l3kernel` is regarded by the LaTeX
+team as stable. There may still be changes to some functions, but these will be
+very minor when compared to the scope of `l3kernel`. In particular, no functions
+will be removed, although some may be deprecated.
Programmers making use of `l3kernel` are *strongly* encouraged to subscribe to
the LaTeX-L mailing list (see below): announcements concerning the deprecation
@@ -27,22 +28,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 `\ifincsname` 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
----------