[latex3-commits] [git/LaTeX3-latex3-latex2e] gh1033: Add \DeclareUppercaseMapping, etc. (c8765916)

[Joseph Wright]

Repository : https://github.com/latex3/latex2e
On branch  : gh1033
Link       : https://github.com/latex3/latex2e/commit/c8765916c8a514d0e01e5723b1f4a22c450e1fb0

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

commit c8765916c8a514d0e01e5723b1f4a22c450e1fb0
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Wed Apr 19 20:34:11 2023 +0100

    Add \DeclareUppercaseMapping, etc.


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

c8765916c8a514d0e01e5723b1f4a22c450e1fb0
 base/changes.txt      |  6 ++++++
 base/doc/ltnews37.tex | 19 +++++++++++++++++++
 base/doc/usrguide.tex | 15 ++++++++++++++-
 base/ltfinal.dtx      | 28 +++++++++++++++++++++++++++-
 4 files changed, 66 insertions(+), 2 deletions(-)

diff --git a/base/changes.txt b/base/changes.txt
index 7ea5523f..9ad40e33 100644
--- a/base/changes.txt
+++ b/base/changes.txt
@@ -6,6 +6,12 @@ completeness or accuracy and it contains some references to files that
 are not part of the distribution.
 ================================================================================
 
+2023-04-19  Joseph Wright  <joseph.wright at latex-project.org>
+
+	* ltfinal.dtx (subsection{Lccodes and uccodes}):
+	Add \DeclareLowercaseMapping, \DeclareTitlecaseMapping and
+	\DeclareUppercaseMapping (gh/1033)
+
 2023-04-19  Phelype Oleinik  <phelype.oleinik at latex-project.org>
 
 	* lthooks.dtx (subsection{Specifying code for next invocation}):
diff --git a/base/doc/ltnews37.tex b/base/doc/ltnews37.tex
index 3bda6478..718d195d 100644
--- a/base/doc/ltnews37.tex
+++ b/base/doc/ltnews37.tex
@@ -341,6 +341,25 @@ line.
 %
 \githubissue{1015}
 
+\subsection{\cs{DeclareLowercaseMapping}, \cs{DeclareTitlecaseMapping}
+  and \cs{DeclareUppercaseMapping}}
+
+The move from a case-changing approach using \cs{lccode} and \cs{uccode} data
+to one where information is stored by a kernel-managed structure left a gap in
+the ability of the user to \emph{tune} the case changing outcomes. This has now
+been addressed by the addition of three commands
+\begin{itemize}
+  \item \cs{DeclareLowercaseMapping}
+  \item \cs{DeclareTitlecaseMapping}
+  \item \cs{DeclareUppercaseMapping}
+\end{itemize}
+which can be used to customise the outcome for codepoints. This can be apply
+generally or to a specific locale (see also the next section). A small number
+of pre-defined customisations have been set up in the kernel where the outcomes
+for \pdfTeX{} should be different for those from Unicode engines.
+%
+\githubissue{1033}
+
 \subsection{\cs{BCPdata}}
 
 Improvements in the Unicode handling for case changing have highlighted that
diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex
index f06850af..b7d550ca 100644
--- a/base/doc/usrguide.tex
+++ b/base/doc/usrguide.tex
@@ -1216,8 +1216,21 @@ cases
   \item Lowercasing
   \item Titlecasing (only applies for the start of the input)
 \end{itemize}
+
 The command \cs{DeclareCaseChangeEquivalent} provides a way to substitute a
 command by an alternative version when it is found inside a case changing
-situation.
+situation. There are three commands for customising the case changing of
+codepoints
+\begin{decl}
+  |\DeclareLowercaseMapping| \oarg{locale} \arg{codepoint} \arg{output} \\
+  |\DeclareTitlecaseMapping| \oarg{locale} \arg{codepoint} \arg{output} \\
+  |\DeclareUppercaseMapping| \oarg{locale} \arg{codepoint} \arg{output}
+\end{decl}
+All three take a \meta{codepoint} (as an integer expression) and will
+result in the \meta{output} being produced under the appropriate case changing
+operation. The optional \meta{locale} can be given if the mapping should only
+apply to a specific one: this is given in BCP-47 format.
+
+All three take the same arguments
 
 \end{document}
diff --git a/base/ltfinal.dtx b/base/ltfinal.dtx
index f5d0474f..054066f0 100644
--- a/base/ltfinal.dtx
+++ b/base/ltfinal.dtx
@@ -33,7 +33,7 @@
 %<*driver>
 % \fi
 \ProvidesFile{ltfinal.dtx}
-             [2023/04/17 v2.3a LaTeX Kernel (Final Settings)]
+             [2023/04/19 v2.3b LaTeX Kernel (Final Settings)]
 % \iffalse
 \documentclass{ltxdoc}
 \GetFileInfo{ltfinal.dtx}
@@ -1087,6 +1087,9 @@
 % \begin{macro}{\AddToNoCaseChangeList}
 % \begin{macro}{\CaseSwitch}
 % \begin{macro}{\DeclareCaseChangeEquivalent}
+% \begin{macro}{\DeclareLowercaseMapping}
+% \begin{macro}{\DeclareTitlecaseMapping}
+% \begin{macro}{\DeclareUppercaseMapping}
 % \begin{macro}{\@uclclist}
 %
 %
@@ -1196,6 +1199,8 @@
 %
 % \changes{v2.2u}{2022/06/02}{Add \cs{NoCaseChange}}
 % \changes{v2.2u}{2022/06/30}{Add \cs{AddToNoCaseChangeList}}
+% \changes{v2.3b}{2023/04/19}{Add \cs{DeclareLowercaseMapping},
+%   \cs{DeclareTitlecaseMapping} and \cs{DeclareUppercaseMapping}}
 % |\NoCaseChange| protects its argument from the case change functions.
 %
 % |\AddToNoCaseChangeList| Allows new commands to protect their arguments, eg
@@ -1209,6 +1214,24 @@
 \cs_new_eq:NN \CaseSwitch \text_case_switch:nnnn
 \cs_new_eq:NN \DeclareCaseChangeEquivalent
   \text_declare_case_equivalent:Nn
+\NewDocumentCommand \DeclareLowercaseMapping { o m m }
+  {
+    \IFNoValueTF {#1}
+      { \text_declare_lowercase_mapping:nn {#2} {#3} }
+      { \text_declare_lowercase_mapping:nnn {#2} {#1} {#3} }
+  }
+\NewDocumentCommand \DeclareTitlecaseMapping { o m m }
+  {
+    \IFNoValueTF {#1}
+      { \text_declare_titlecase_mapping:nn {#2} {#3} }
+      { \text_declare_titlecase_mapping:nnn {#2} {#1} {#3} }
+  }
+\NewDocumentCommand \DeclareUppercaseMapping { o m m }
+  {
+    \IFNoValueTF {#1}
+      { \text_declare_uppercase_mapping:nn {#2} {#3} }
+      { \text_declare_uppercase_mapping:nnn {#2} {#1} {#3} }
+  }
 \ExplSyntaxOff
 %    \end{macrocode}
 %
@@ -1227,6 +1250,9 @@
 % \end{macro}
 % \end{macro}
 % \end{macro}
+% \end{macro}
+% \end{macro}
+% \end{macro}
 %
 % \changes{v1.0h}{1994/05/13}{Added output enc stuff}
 % \changes{v1.0i}{1994/05/16}{moved output enc stuff to lfonts}