Adapt renaming: `\cs_argument_spec:N` -> `\cs_parameter_spec:N`

[muzimuzhi]

Brief outline of the enhancement

LaTeX2e generally cannot add new features without an extreme amount of care to accommodate backwards compatibility. Please do not be offended if your request is closed for being infeasible.

(originally found in https://github.com/latex3/latex2e/issues/1009#issuecomment-1459433841)

latex3 function \cs_argument_spec:N has been renamed to \cs_parameter_spec:N, and the old name is softly deprecated. See https://github.com/latex3/latex3/blob/b693d92d5819e5fe17bf5b19a2bf5c351bd437e3/l3kernel/l3deprecation.dtx#L441-L448

% \begin{macro}[EXP]{\cs_argument_spec:N}
%   For the present, do not deprecate fully as \LaTeXe{} will need to catch
%   up: one for Fall 2022.
%    \begin{macrocode}
%\__kernel_patch_deprecation:nnNNpn { 2022-06-24 } { \cs_parameter_spec:N }
\cs_gset:Npn \cs_argument_spec:N { \cs_parameter_spec:N }
%    \end{macrocode}
% \end{macro}

Current uses of \cs_argument_spec:N in latex2e:

$ grep -rn --exclude-dir build 'cs_argument_spec\|@expl@cs@argument@spec@@' .
./texmf/tex/latex/l3kernel/expl3-code.tex:36145:  { \cs_argument_spec:N } { 2021-07-01 }
./texmf/tex/latex/l3kernel/expl3-code.tex:36162:\cs_gset:Npn \cs_argument_spec:N { \cs_parameter_spec:N }
./texmf/tex/latex/l3packages/xparse/xparse-2018-04-12.sty:1953:        \exp_args:Nf \tl_if_empty:nT { \cs_argument_spec:N #1 }
./texmf/tex/latex/l3packages/xparse/xparse-generic.tex:1834:        \exp_args:Nf \tl_if_empty:nT { \cs_argument_spec:N #1 }
./base/ltcmd.dtx:4424:        \exp_args:Nf \tl_if_empty:nT { \cs_argument_spec:N #1 }
./base/ltdefns.dtx:2019:    \@expl@cs@argument@spec@@N#1->\@expl@cs@replacement@spec@@N#1}}
./base/ltdefns.dtx:2120:  \typeout{\@expl@cs@argument@spec@@N#1->%
./base/ltdefns.dtx:2142:    \else:^^J\@expl@cs@argument@spec@@N#1->%
./base/ltdefns.dtx:2161:   \@expl@cs@argument@spec@@N#1->\@expl@cs@replacement@spec@@N#1.}}
./base/ltcmdhooks.dtx:764:%   counting the number of characters in the \cs{cs_argument_spec:N} of
./base/ltcmdhooks.dtx:771:        \exp_args:Nf \str_count:n { \cs_argument_spec:N #2 } / 2
./base/ltcmdhooks.dtx:1078:%   \cs{cs_argument_spec:N} is empty, and call
./base/ltcmdhooks.dtx:1084:    \str_if_eq:eeTF { \cs_argument_spec:N #1 } { }
./base/ltexpl.dtx:361:\cs_gset_eq:NN \@expl@cs@argument@spec@@N \cs_argument_spec:N
./base/ltexpl.dtx:390:%<latexrelease>\let \@expl@cs@argument@spec@@N \@undefined

To apply the renaming, it seems to me

• the uses in texmf directory is not controlled by latex2e hence should be intact,
• \@expl@cs@argument@spec@@N need to be renamed to \@expl@cs@parameter@spec@@N. Will this change interact with the rollback mechanism?

[PhelypeOleinik]

• the uses in texmf directory is not controlled by latex2e hence should be intact

Yes

• \@expl@cs@argument@spec@@N need to be renamed to \@expl@cs@parameter@spec@@N. Will this change interact with the rollback mechanism?

Yes, many... er... interesting interactions :)

Though since it's just a rename, I'd bite the bullet and forget about rollback:

• If you're on a new (future) kernel and want to roll back, and all functions in latexrelease already have parameter_spec (instead of argument_spec) in their definition, there is no issue. This is the main scenario latexrelease is supposed to support;
• If you're on a very old kernel rolling forward, latexrelease will define parameter@spec anyway;
• The problem is if you're on a middle ground, then the kernel has argument@spec but the functions inside have parameter@spec. This case is more or less uncommon, so I'd blissfully ignore :)

[josephwright]

@PhelypeOleinik I don't see that we need rollback here: this is internal stuff and the name should really not matter to others.

[PhelypeOleinik]

@josephwright Yeah, in most cases it won't be noticeable, except when a not-too-old (i.e. \@expl@cs@argument@spec@@N already exists) kernel trying to roll forward... But I believe I can count the number of people doing that on the fingers of one hand while still holding my coffee ;-)

[FrankMittelbach]

not looked at the details, but the problem with rolling forward is that if, say, Overleaf is the one that has the not too old kernel, it might suddenly be the one that a lot of people have. So the question is perhaps are we already passed that or not?

[PhelypeOleinik]

I can take a look, to see what's needed to fully support roll forward for this case. If the main target is to support what version of LaTeX Overleaf has, it doesn't need too much, I guess.

[josephwright]

It seems best to leave the LaTeX2e name alone and simply note that it should have been named differently: can be covered with a code comment.

[josephwright]

Actually, looking again it's a bit more tricky. I suggest we push this one forward for a while: wait for a reasonable spread of the new name in expl3, then simply change. Probably going to be year or so.

[github-actions[bot]]

This issue has been automatically marked as stale because it has not had recent activity.

[josephwright]

We need to wait here ... probably several years :(

[josephwright]

Thinking again about this: I suspect almost everyone who has an updated kernel will have an updated expl3 - time to make the change?

[FrankMittelbach]

I guess so, assuming we have another dev release in which the change is included.

[josephwright]

I'll sort the 2e part for the next dev release - the l3 change will come after that is out as a main release