summaryrefslogtreecommitdiff
path: root/macros/latex-dev/base/usrguide.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-05-26 03:02:08 +0000
committerNorbert Preining <norbert@preining.info>2023-05-26 03:02:08 +0000
commit8057c647880f05a2624b3d04ab0eb38d5cbf8c18 (patch)
tree2df10dbc859977e89de9b6797303c039106aca37 /macros/latex-dev/base/usrguide.tex
parented4c98e3a1f3e2160094ac1b05cfc304832cce4d (diff)
CTAN sync 202305260302
Diffstat (limited to 'macros/latex-dev/base/usrguide.tex')
-rw-r--r--macros/latex-dev/base/usrguide.tex93
1 files changed, 79 insertions, 14 deletions
diff --git a/macros/latex-dev/base/usrguide.tex b/macros/latex-dev/base/usrguide.tex
index f06850afaa..b1039a3595 100644
--- a/macros/latex-dev/base/usrguide.tex
+++ b/macros/latex-dev/base/usrguide.tex
@@ -32,9 +32,10 @@
\usepackage[T1]{fontenc} % needed for \textbackslash in tt
\usepackage{csquotes}
+\usepackage{url}
\title{\LaTeX\ for authors --- current version}
-\author{\copyright~Copyright 2020-2022, \LaTeX\ Project Team.\\
+\author{\copyright~Copyright 2020-2023, \LaTeX\ Project Team.\\
All rights reserved.%
\footnote{This file may be distributed and/or modified under the
conditions of the \LaTeX{} Project Public License, either version 1.3c
@@ -42,7 +43,7 @@
\texttt{usrguide.tex} for full details.}%
}
-\date{2022-07-05}
+\date{2023-05-23}
\NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}}
\NewDocumentCommand\marg{m}{\arg{#1}}
@@ -340,6 +341,12 @@ in \pkg{amsmath} environments, which in the terms here would be defined as
\NewDocumentCommand\\{!s !o}{ ... }
\end{verbatim}
+Also notable when using optional arguments in the last position is that \TeX{}
+will necessarily look ahead for the argument opening token. This means that
+the value of |\inputlineno| will be `out by one' if such a trailing optional
+argument is \emph{not} present and the command ends a line; it will be one
+greater than the line number containing the last mandatory argument.
+
\subsection{`Embellishments'}
\label{sec:cmd:embellishment}
@@ -636,7 +643,19 @@ processed argument can be further processed using a mapping function
If only a single character \meta{token} is used for the split, any
category code $13$ (active) character matching the \meta{token} will
be replaced before the split takes place.
-Spaces are trimmed at each end of each item parsed.
+Spaces are trimmed at each end of each item parsed. Exactly one set
+of braces will be stripped if an entire item is surrounded by them,
+i.e.~the following inputs and outputs result (each separte item as
+a brace group).
+\begin{verbatim}
+a ==> {a}
+{a} ==> {a}
+{a}b ==> {{a}b}
+a,b ==> {a}{b}
+{a},b ==> {a}{b}
+a,{b} ==> {a}{b}
+a,{b}c ==> {a}{{b}c}
+\end{verbatim}
\begin{decl}
|\ProcessList| \arg{list} \arg{function}
@@ -716,7 +735,7 @@ put that code at the end of the \meta{start code}. Nevertheless this
Environments that use this feature can be nested.
-\subsection{Fully-expandable document commands}
+\subsection{Fully-expandable document commands\label{sec:ltcmd:expandable}}
Document commands created using \cs{NewDocumentCommand}, etc.\@, are normally
created so that they do not expand unexpectedly. This is done using engine
@@ -724,7 +743,7 @@ features, so is more powerful than \LaTeXe{}'s \cs{protect} mechanism. There
are \emph{very rare} occasion when it may be useful to create functions using a
expansion-only grabber. This imposes a number of restrictions on the
nature of the arguments accepted by a function, and the code it implements.
-This facility should only be used when \emph{absolutely necessary}.
+This facility should only be used when \emph{necessary}.
\begin{decl}
|\NewExpandableDocumentCommand| \arg{cmd} \arg{arg spec} \arg{code} \\
@@ -755,6 +774,25 @@ available:
in the standard version.
\end{itemize}
+\subsection{Commands at the start of tabular cells}
+
+Creating commands that are used at the start of tabular cells imposes
+some restrictions on the underlying implementation. The standard \LaTeX{}
+tabular environments (\texttt{tabular}, etc.) use a mechanism which requires
+that any command wrapping \cs{multicolumn} or similar must be
+`expandable'. This is \emph{not} the case for commands created using
+\cs{NewDocumentCommand}, etc., which as detailed in
+Section~\ref{sec:ltcmd:expandable} use an engine feature which prevents
+such `expansion'. Therefore, to create such wrappers for use at the start
+of tabular cells, you must use \cs{NewExpandableDocumentCommand}, for example
+\begin{verbatim}
+\NewExpandableDocumentCommand\MyMultiCol{m}{\multicolumn{3}{c}{#1}}
+\begin{tabular}{lcr}
+a & b & c \\
+\MyMultiCol{stuff} \\
+\end{tabular}
+\end{verbatim}
+
\subsection{Details about argument delimiters}
In normal (non-expandable) commands, the delimited types look for the
@@ -844,23 +882,23 @@ The argument specifications for document commands and environments are
available for examination and use.
\begin{decl}
- |\GetDocumentCommandArgSpec| \arg{function} \\
+ |\GetDocumentCommandArgSpec| \arg{cmd} \\
|\GetDocumentEnvironmentArgSpec| \arg{environment}
\end{decl}
These functions transfer the current argument specification for the
-requested \meta{function} or \meta{environment} into the token list
-variable \cs{ArgumentSpecification}. If the \meta{function} or
+requested \meta{cmd} or \meta{environment} into the token list
+variable \cs{ArgumentSpecification}. If the \meta{cmd} or
\meta{environment} has no known argument specification then an error
is issued. The assignment to \cs{ArgumentSpecification} is local to
the current \TeX{} group.
\begin{decl}
- |\ShowDocumentCommandArgSpec| \arg{function} \\
+ |\ShowDocumentCommandArgSpec| \arg{cmd} \\
|\ShowDocumentEnvironmentArgSpec| \arg{environment}
\end{decl}
These functions show the current argument specification for the
-requested \meta{function} or \meta{environment} at the terminal. If
-the \meta{function} or \meta{environment} has no known argument
+requested \meta{cmd} or \meta{environment} at the terminal. If
+the \meta{cmd} or \meta{environment} has no known argument
specification then an error is issued.
@@ -1149,11 +1187,11 @@ therefore shows the same syntax peculiars as discussed
above. Nevertheless, in practice they are usually sufficient. For
example
\begin{verbatim}
-\newcommand\calulateheight[1]{%
+\newcommand\calculateheight[1]{%
\setlength\textheight{\dimeval{\topskip+\baselineskip*\inteval{#1-1}}}}
\end{verbatim}
sets the \cs{textheight} to the appropriate value if a page should
-hold a specific number of text lines. Thus after |\calulateheight{40}|
+hold a specific number of text lines. Thus after |\calculateheight{40}|
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.
@@ -1216,8 +1254,35 @@ 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
+(\url{https://en.wikipedia.org/wiki/IETF_language_tag}). For example,
+the kernel customises the mapping for U+01F0 (\v{j}) when uppercasing in
+8-bit engines:
+\begin{quotation}
+ |\DeclareUppercaseMapping{"01F0}{\v{J}}|
+\end{quotation}
+as there is no pre-composed \v{J} character, and this is problematic if
+the engine does not support Unicode natively. Similarly, to set a locale
+\texttt{xx} to behave in the same way as Turkish and retain the difference
+between dotted- and dotless-i, one could use for example
+\begin{quotation}
+ |\DeclareLowercaseMapping{xx}{"0049}{\i}|\\
+ |\DeclareLowercaseMapping{xx}{"0130}{i}|\\
+ |\DeclareUppercaseMapping{xx}{"0069}{\.{I}}|\\
+ |\DeclareUppercaseMapping{xx}{"0131}{I}|
+\end{quotation}
\end{document}