[latex3-commits] [git/LaTeX3-latex3-latex2e] hotfix/gh889: Add some documentation for the new case changer (707b87e6)

[Joseph Wright]

Repository : https://github.com/latex3/latex2e
On branch  : hotfix/gh889
Link       : https://github.com/latex3/latex2e/commit/707b87e69cdeef9330a9954687f084e0243c9514

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

commit 707b87e69cdeef9330a9954687f084e0243c9514
Author: Joseph Wright <joseph.wright at morningstar2.co.uk>
Date:   Tue Jul 5 08:42:07 2022 +0100

    Add some documentation for the new case changer


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

707b87e69cdeef9330a9954687f084e0243c9514
 base/doc/usrguide3.tex | 57 +++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 56 insertions(+), 1 deletion(-)

diff --git a/base/doc/usrguide3.tex b/base/doc/usrguide3.tex
index efec9ad2..a148c77e 100644
--- a/base/doc/usrguide3.tex
+++ b/base/doc/usrguide3.tex
@@ -37,7 +37,7 @@
 \author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\
    All rights reserved.}
 
-\date{2022-02-19}
+\date{2022-07-05}
 
 \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
 \NewDocumentCommand\marg{m}{\arg{#1}}
@@ -1054,4 +1054,59 @@ it is set to \dimeval{\topskip+\baselineskip*\inteval{40-1}}, given
 the values \cs{topskip} (\dimeval{\topskip}) and \cs{baselineskip}
 (\dimeval{\baselineskip}) in the current document.
 
+\section{Case changing}
+
+\TeX{} provides two primitives \cs{uppercase} and \cs{lowercase} for changing
+the case of text. However, these have a range of limitations: they only change
+the case of explicit characters, do not account for the surrounding context, do
+not support UTF-8 input with 8-bit engines, etc. To overcome this problem,
+\LaTeX{} provides the commands \cs{MakeUppercase}, \cs{MakeLowercase} and
+\cs{MakeTitlecase}: these offer significant enhancement over the \TeX{}
+primitives. These commands are engine-robust (\cs{protected}), and so
+can be used in moving arguments.
+
+Upper- and lower-casing are well-understood in general conversation.
+Titlecasing here follows the definition given by the Unicode Consortium: the
+first character of the input will be converted to (broadly) uppercase, and the
+rest of the input to lowercase. The full range of Unicode UTF-8 input can be
+supported, with the proviso that at present the characters set up with 8-bit
+engines match those available in standard input encodings (|T1|, |T2|, |LGR|).
+\begin{quotation}
+  \begin{tabular}{rl}
+    |\MakeUppercase{hello WORLD ßüé}| & \MakeUppercase{hello WORLD ßüé} \\
+    |\MakeLowercase{hello WORLD ßüé}| & \MakeLowercase{hello WORLD ßüé} \\
+    |\MakeTitlecase{hello WORLD ßüé}| & \MakeTitlecase{hello WORLD ßüé} \\
+  \end{tabular}
+\end{quotation}
+
+The input given to these commands is `expanded' before case changing is
+applied. This means that any commands within the input that convert to pure
+text will be case changed. Mathematical content is automatically excluded, as
+are the arguments to the commands \cs{label}, \cs{ref}, \cs{cite}, \cs{begin}
+and \cs{end}. Additional exclusions can be added using the command
+\cs{AddToNoCaseChangeList}. Input can be excluded from case changing using the
+command \cs{NoCaseChange}.
+\begin{quotation}
+  \begin{tabular}{rl}
+    |\MakeUppercase{Some text $y = mx + c$}|
+      & \MakeUppercase{Some text $y = mx + c$} \\
+    |\MakeUppercase{\NoCaseChange{iPhone}}|
+      & \MakeLowercase{\NoCaseChange{iPhone}} \\
+  \end{tabular}
+\end{quotation}
+
+To allow robust commands to be used within case changing \emph{and} to produce
+the expected output, two additional control commands are available.
+\cs{CaseSwitch} allows the user to specify the result for the four possible
+cases
+\begin{itemize}
+  \item No case changing
+  \item Uppercasing
+  \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.
+
 \end{document}