From b5d6c2d4935965593e8bfffaae1dbdd0cbeaeef0 Mon Sep 17 00:00:00 2001 From: Ulrike Fischer Date: Fri, 24 Jan 2025 00:33:17 +0100 Subject: [PATCH 1/4] Update documentation for textcolor for gh1474 (#1629) * document space handling of textcolor, issue #1474 * from review: change wording * from review: change wording * add ltnews entry * remove backslash * from review --- base/doc/ltnews41.tex | 13 +++++++++++-- required/graphics/color.dtx | 6 ++++-- required/graphics/grfguide.tex | 14 ++++++++------ 3 files changed, 23 insertions(+), 10 deletions(-) diff --git a/base/doc/ltnews41.tex b/base/doc/ltnews41.tex index 04a186bcb..1cfc7fc98 100644 --- a/base/doc/ltnews41.tex +++ b/base/doc/ltnews41.tex @@ -189,7 +189,7 @@ \section{Replacement for the legacy mark mechanism} \section{News from Tagged PDF project} -The \texttt{testphase} key now takes also the value \texttt{latest}. +The \texttt{testphase} key now takes also the value \texttt{latest}. This will load all modules that we recommend so that it is not necessary to specify individual modules. The list of loaded modules will be adjusted as needed when the project progresses. It is also written to the log. @@ -466,6 +466,15 @@ \subsection{Process global options once per package} % \githubissue{1619} +\section{Documentation} +\subsection{Clarifying space handling of \cs{textcolor}} + +In contrast to other \cs{text}-commands like \cs{textbf} or \cs{textrm}, +the command \cs{textcolor} gobbles spaces at the start of its argument, so \verb=Hello\textcolor{red}{ World}= will output Hello\textcolor{red}{ World}. +There are technical as well as compatibility reasons for this, so the behavior will not change. This has now been clarified in the documentation. +% +\githubissue{1474} + %\section{Changes to packages in the \pkg{amsmath} category} \section{Changes to packages in the \pkg{graphics} category} @@ -498,7 +507,7 @@ \subsection{\pkg{multicol}:\ Full support for extended marks} \subsection{\pkg{array}:\ Improve preamble setup code for \texttt{p} and friends} While the preamble of a \env{tabular} or \env{array} is being built -the arguments to \texttt{p}, \texttt{m}, or \texttt{b} columns got +the arguments to \texttt{p}, \texttt{m}, or \texttt{b} columns got expanded several times. This is normally harmless because that argument contains usually just a dimension. However, in a case like \verb=p{\fpeval{15}pt}= this resulted in an error, because \cs{fpeval} diff --git a/required/graphics/color.dtx b/required/graphics/color.dtx index eb2d5e4cc..a35d6f6e9 100644 --- a/required/graphics/color.dtx +++ b/required/graphics/color.dtx @@ -21,7 +21,7 @@ % \ProvidesFile{color.drv} % \fi % \ProvidesFile{color.dtx} - [2024/06/23 v1.3e Standard LaTeX Color (DPC)] + [2025/01/14 v1.3e Standard LaTeX Color (DPC)] % % \iffalse %<*driver> @@ -458,7 +458,9 @@ % specified colour, but then the colour reverts to its previous value. % The naming is by analogy with |\textrm| (as opposed to |\rm| and % |\rmfamily|) although it is slightly a misnomer as the command also -% works in math-mode. +% works in math-mode. In contrast to |\textrm|, the command gobbles spaces +% at the begin of its argument, so |Hello\textcolor{red}{ World}| will +% output Hello\textcolor{red}{ World}. % % Since December 95, in fact this command has one other difference % from |\color|. It calls |\leavevmode| to ensure the start of diff --git a/required/graphics/grfguide.tex b/required/graphics/grfguide.tex index 4dfdb4ca8..a5be49f18 100644 --- a/required/graphics/grfguide.tex +++ b/required/graphics/grfguide.tex @@ -63,7 +63,7 @@ \title{Packages in the `graphics' bundle} \author{D. P. Carlisle \and The \LaTeX\ Project} -\date{2024-12-31} +\date{2025-01-14} \maketitle @@ -231,8 +231,9 @@ \subsubsection{Using predefined colours} \end{decl} This is a \emph{declaration}, like |\bfseries|. It changes the current -colour to \m{name} until the end of the current group or -environment. +colour to \m{name} until the end of the current group, or +environment. It does not automatically start horizontal mode so typically at +the start of a paragraph it should be used in combination with a |\leavevmode|. An alternative command syntax is to use a \emph{command} form that takes the text to be coloured as an \emph{argument}. This is similar @@ -242,9 +243,10 @@ \subsubsection{Using predefined colours} |\textcolor|\arg{name}\arg{text} \end{decl} - -So the above is essentially equivalent to -|{\color|\arg{name}\emph{text}|}|. +The command switches to horizontal mode, +so the above is essentially equivalent to +|{\leavevmode\color|\arg{name}\emph{text}|}|. In contrast to |\textbf|, +the command gobbles spaces at the start of its argument, so |Hello\textcolor{red}{ World}| will output Hello\textcolor{red}{ World}. \subsection{Using Colours in math formulas} From 0b7d80350752982773ad6a48761a29a615cc73c7 Mon Sep 17 00:00:00 2001 From: Joseph Wright Date: Fri, 24 Jan 2025 07:19:23 +0000 Subject: [PATCH 2/4] Doc tweaks from JS (skillmon) --- base/doc/usrguide.tex | 4 ++-- base/ltcmd.dtx | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex index 11616e65f..6b1c45b0f 100644 --- a/base/doc/usrguide.tex +++ b/base/doc/usrguide.tex @@ -43,7 +43,7 @@ \texttt{usrguide.tex} for full details.}% } -\date{2025-01-23} +\date{2025-01-24} \NewDocumentCommand\cs{m}{\texttt{\textbackslash\detokenize{#1}}} \NewDocumentCommand\marg{m}{\arg{#1}} @@ -903,7 +903,7 @@ \subsection{Verbatim environments} \texttt{D}~specification argument immediately before an \texttt{c}~specification. This means that when the optional argument is absent, the first character of the next line will be read properly. Issues may arise if -\emph{multiple} optional arguments are used before an \texttt{c}~specification, +\emph{multiple} optional arguments are used before a \texttt{c}~specification, and are therefore strongly discouraged. For technical reasons, we recommend that spaces are \emph{not} ignored when diff --git a/base/ltcmd.dtx b/base/ltcmd.dtx index 27d25fc30..54123c67e 100644 --- a/base/ltcmd.dtx +++ b/base/ltcmd.dtx @@ -35,7 +35,7 @@ % % \begin{macrocode} \def\ltcmdversion{v1.3a} -\def\ltcmddate{2025-01-23} +\def\ltcmddate{2025-01-24} % \end{macrocode} % %<*driver> @@ -138,7 +138,7 @@ % % \begin{variable}{\l_@@_total_args_int} % \changes{v1.3a}{2025-01-23}{New variable} -% The total number of arguments found during normalization: this is needed +% The total number of arguments found during normalization: this is required % where special action is needed for the penultimate argument. % \begin{macrocode} \int_new:N \l_@@_total_args_int From eb67376d7087d7fa169e23ea2584fb51a60212f2 Mon Sep 17 00:00:00 2001 From: Joseph Wright Date: Fri, 24 Jan 2025 07:31:59 +0000 Subject: [PATCH 3/4] Further tweaks from JS --- base/doc/ltnews41.tex | 2 +- base/doc/usrguide.tex | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/base/doc/ltnews41.tex b/base/doc/ltnews41.tex index 1cfc7fc98..b139b8a79 100644 --- a/base/doc/ltnews41.tex +++ b/base/doc/ltnews41.tex @@ -256,7 +256,7 @@ \subsection{Collecting environment bodies verbatim} In this release, a new specifier~\texttt{c} is introduced, which collects the body of an environment in a verbatim-like way. Like the existing -\texttt{v}~specification, each separate line is marked by the special +\texttt{+v}~specification, each separate line is marked by the special \cs{obeyedline} marker, which as standard issues a normal paragraph. Thus, this new specifier is usable both for typesetting and collecting file contents (the letter~\texttt{c} indicates \enquote{collect code}). Thus, we may use diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex index 6b1c45b0f..b3192c17c 100644 --- a/base/doc/usrguide.tex +++ b/base/doc/usrguide.tex @@ -888,7 +888,7 @@ \subsection{Verbatim environments} \texttt{v} specification, newlines are stored as \cs{obeyedline}. In a similar fashion to the \texttt{b}~specification, by default \emph{newlines} are trimmed at both ends of the body. Putting the prefix |!| before \texttt{c} suppresses -space-trimming. +this trimming. Collection of the body takes place on a line-by-line basis: content is collected up to the end-of-line in the source, then examined before storage. From 19d68da661f13733d412b76f3b84d003946ad465 Mon Sep 17 00:00:00 2001 From: Joseph Wright Date: Fri, 24 Jan 2025 07:41:46 +0000 Subject: [PATCH 4/4] Doc tweaks from CR --- base/doc/usrguide.tex | 18 +++++++++--------- base/ltcmd.dtx | 2 +- 2 files changed, 10 insertions(+), 10 deletions(-) diff --git a/base/doc/usrguide.tex b/base/doc/usrguide.tex index b3192c17c..ace4d24f8 100644 --- a/base/doc/usrguide.tex +++ b/base/doc/usrguide.tex @@ -863,7 +863,7 @@ \subsection{Typesetting verbatim-like material} \subsection{Verbatim environments} \label{sec:cmd:verbenv} -In some cases, as well as grabbing an environment body you will want the +In some cases, when grabbing the body of an environment you will want the contents to be treated verbatim. This is available using the argument specification~\texttt{c}. Like the \texttt{b} specification, this has to be the last one. Thus for example @@ -875,7 +875,7 @@ \subsection{Verbatim environments} $y = mx + c$ \end{MyVerbatim} \end{verbatim} -will typeset +will typeset verbatim the content, thus: \NewDocumentEnvironment{MyVerbatim}{!O{\ttfamily} c} {\begin{center} #1 #2\end{center}} {} \begin{MyVerbatim}[\ttfamily\itshape] @@ -883,12 +883,12 @@ \subsection{Verbatim environments} $y = mx + c$ \end{MyVerbatim} -As grabbing the entire contents verbatim means there are no \cs{par} tokens, -newlines are always permitted: there is no need for a |+| here. As for the -\texttt{v} specification, newlines are stored as \cs{obeyedline}. In a similar -fashion to the \texttt{b}~specification, by default \emph{newlines} are trimmed -at both ends of the body. Putting the prefix |!| before \texttt{c} suppresses -this trimming. +Since grabbing the entire contents verbatim will result in there being no +\cs{par} tokens, newlines are always permitted: there is no need for a +|+|~modifier here. As for the \texttt{v} specification, newlines are stored as +\cs{obeyedline}. In a similar fashion to the \texttt{b}~specification, by +default \emph{newlines} are trimmed at both ends of the body. Putting the +prefix |!| before \texttt{c} suppresses this trimming. Collection of the body takes place on a line-by-line basis: content is collected up to the end-of-line in the source, then examined before storage. @@ -908,7 +908,7 @@ \subsection{Verbatim environments} For technical reasons, we recommend that spaces are \emph{not} ignored when searching for an optional argument before an \texttt{c} specification: this can -be achieved by adding the \texttt{!} modifier as showing in the example. +be achieved by adding the \texttt{!} modifier as shown in the example. However, this is left as a choice for the user. \subsection{Performance} diff --git a/base/ltcmd.dtx b/base/ltcmd.dtx index 54123c67e..acb9aac3b 100644 --- a/base/ltcmd.dtx +++ b/base/ltcmd.dtx @@ -341,7 +341,7 @@ % % \begin{variable}{\l_@@_final_verb_bool} % \changes{v1.3a}{2025-01-23}{New variable} -% Needed to establish if optional arguments should be collected +% Needed to establish whether optional arguments should be collected % \enquote{verbatim safe}. % \begin{macrocode} \bool_new:N \l_@@_final_verb_bool