Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

extend label to five data and add hook #956

Merged
merged 25 commits into from May 16, 2023
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
23 changes: 23 additions & 0 deletions base/doc/ltnews37.tex
Expand Up @@ -149,6 +149,29 @@ \section{New or improved commands}
%
\githubissue{xxx}

\subsection{Extension of the \cs{label} command}

Up to now the \cs{label} command stored in standard \LaTeX{} into the
\cs{newlabel} command in the \texttt{.aux} file two data:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

would use "values" not "data" even if data is correct in its plural

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or "data items"

\cs{@currentlabel}, which normally contains the state of the current
counter, and \cs{thepage} for the current page number. \pkg{hyperref} and
\pkg{nameref} patch the \cs{label} command to store five data:
Additionally they save \cs{@currentlabelname}, which normally contains the
current title text and can be retrieved with \cs{nameref} and
\cs{@currentHref} which is the name of the destination needed to create an
active link. The fifth data container is currently only used if external
references are loaded with the \pkg{xr-hyper} package.

Starting with this release the number of arguments have be unified.
\cs{label} now writes a
\cs{newlabel} command containing five data: \cs{@currentlabel},
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

with five arguments

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No! They are not (and in ltxref never become) arguments of anything --

Suggestion: ... command that stores, in its second argument, the following five items of data:

Copy link
Contributor

@car222222 car222222 Dec 5, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

container ==> item

\cs{thepage}, \cs{@currentlabelname}, \cs{@currentHref}. The fifth
container is reserved for the kernel and contains data needed for the
tagged PDF project.

Additionally a hook with the name \texttt{label} has been added. It is
executed before the writing to the \texttt{.aux} file. Code using
the hook can refer to the label argument with \cs{label@name}.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if @currentlabelname etc why \label@name and not @labelargument, ie the @ always in the same position?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

from a general perspective I wonder if there shouldn't actually be 6 arguments (the last 2 key/value lists)
with

  • arg5 reserved for packages to pass stuff around
  • arg6 reserved for the kernel to pass extra stuff around

shold probably be discussed elsewhere, not in this pull.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if @currentlabelname etc why \label@name and not @labelargument, ie the @ always in the same position?

\label@name is the command currently used by nameref. But `@labelargument would be fine with me.

6 arguments (the last 2 key/value lists)

perhaps, but at first the patches from hyperref and nameref should disappear.

Copy link
Contributor

@car222222 car222222 Dec 4, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If changing to 6 items is too difficult, item 6 could contain two sub-items(?), one for holding the user-information (in a well-defined and consistent format) and the other for the kernel.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As discussed yesterday, we can do with one argument as long as we define that datastructure in a way that packages (or users) can add to it in a controlled way. But if not we can indeed use 2 brace groups to separate them if that seems advisable in the end.

Copy link
Contributor

@car222222 car222222 Dec 5, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

argument ==> (data) item


\section{Code improvements}

Expand Down
85 changes: 74 additions & 11 deletions base/ltxref.dtx
Expand Up @@ -33,7 +33,7 @@
%<*driver>
% \fi
\ProvidesFile{ltxref.dtx}
[2022/04/12 v1.1p LaTeX Kernel (Cross Referencing)]
[2022/11/12 v1.1q LaTeX Kernel (Cross Referencing)]
% \iffalse
\documentclass{ltxdoc}
\GetFileInfo{ltxref.dtx}
Expand Down Expand Up @@ -108,7 +108,8 @@
% incremented by the command \refstepcounter{CNT} , which sets
% \@currentlabel == {CNT}{eval(\p@cnt\theCNT)}. The command
% \label{FOO} then writes the following on file \@auxout :
% \newlabel{FOO}{{eval(\@currentlabel)}{eval(\thepage)}}
% \newlabel{FOO}{{eval(\@currentlabel)}{eval(\thepage)}%
% {eval(\@currentlabelname)}{eval(\@currentHref)}{eval(\@kernel@reserved@data)}}
%
% \ref{FOO} ==
% BEGIN
Expand Down Expand Up @@ -228,26 +229,64 @@
%
% RmS 93/09/08: Added setting of refundefined switch.
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2023/06/01}%
%<latexrelease> {\@kernel@sref}{store five arguments}%
\def\@setref#1#2#3{%
\ifx#1\relax
\protect\G@refundefinedtrue
\nfss@text{\reset@font\bfseries ??}%
\@latex@warning{Reference `#3' on page \thepage \space
undefined}%
\else
\expandafter#2#1\null
\expandafter#2#1\@empty\@empty\@empty\null
\fi}
% \end{macrocode}
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
\long\def\@firstoffive#1#2#3#4#5{#1}
\long\def\@secondoffive#1#2#3#4#5{#2}
\def\@kernel@sref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoffive{#1}}
\def\@kernel@spageref#1{\expandafter\@setref\csname r@#1\endcsname
\@secondoffive{#1}}
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2022/06/01}%
%<latexrelease> {\@kernel@sref}{store five arguments}%
%<latexrelease>\def\@setref#1#2#3{%
%<latexrelease> \ifx#1\relax
%<latexrelease> \protect\G@refundefinedtrue
%<latexrelease> \nfss@text{\reset@font\bfseries ??}%
%<latexrelease> \@latex@warning{Reference `#3' on page \thepage \space
%<latexrelease> undefined}%
%<latexrelease> \else
%<latexrelease> \expandafter#2#1\null
%<latexrelease> \fi}
%<latexrelease>\let\@firstoffive\undefined
%<latexrelease>\let\@secondoffive\undefined
%<latexrelease>\def\@kernel@sref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoftwo{#1}}
%<latexrelease>\def\@kernel@spageref#1{\expandafter\@setref\csname r@#1\endcsname
%<latexrelease> \@secondoftwo{#1}}
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease> {\@kernel@sref}{store five arguments}%
%<latexrelease>\def\@setref#1#2#3{%
%<latexrelease> \ifx#1\relax
%<latexrelease> \protect\G@refundefinedtrue
%<latexrelease> \nfss@text{\reset@font\bfseries ??}%
%<latexrelease> \@latex@warning{Reference `#3' on page \thepage \space
%<latexrelease> undefined}%
%<latexrelease> \else
%<latexrelease> \expandafter#2#1\null
%<latexrelease> \fi}
%<latexrelease>\let\@firstoffive\undefined
%<latexrelease>\let\@secondoffive\undefined
%<latexrelease>\let\@kernel@sref\undefined
%<latexrelease>\let\@kernel@spageref\undefined
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2022/06/01}%
%<latexrelease> {\ref}{Add starred reference commands}%
% \end{macrocode}
% \begin{macrocode}
\def\@kernel@sref#1{\expandafter\@setref\csname r@#1\endcsname\@firstoftwo{#1}}
\def\@kernel@spageref#1{\expandafter\@setref\csname r@#1\endcsname
\@secondoftwo{#1}}
\let\@kernel@ref\@kernel@sref
\let\@kernel@pageref\@kernel@spageref
\NewDocumentCommand\ref{s}
Expand Down Expand Up @@ -334,6 +373,7 @@
% \begin{macro}{\label}
% \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected@write}}
% \changes{v1.1d}{1994/11/04}{(ASAJ)Added \cs{protected@edef}}
% \changes{v1.1q}{2022/11/12}{(UFi)extended to store five arguments}
% The commands |\label| and |\refstepcounter| have been changed to
% allow |\protect|'ed commands to work properly. For example,
%\begin{verbatim}
Expand All @@ -343,16 +383,29 @@
% to something like |\foo{4.d}|. Change made 20 Jul 88.
%
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2023/06/01}%
%<latexrelease> {\label}{store five label arguments}%
\providecommand\@currentlabelname{}
\providecommand\@currentHref{}
\providecommand\@kernel@reserved@data{}
\providecommand\label@name{}
\NewHook{label}
\def\label#1{\@bsphack
\begingroup
\def\label@name{#1}%
\UseHook{label}%
\protected@write\@auxout{}%
{\string\newlabel{#1}{{\@currentlabel}{\thepage}}}%
{\string\newlabel{#1}{{\@currentlabel}{\thepage}%
{\@currentlabelname}{\@currentHref}{\@kernel@reserved@data}}}%
\endgroup
\@esphack}
%<latexrelease>\EndIncludeInRelease
% \end{macrocode}
% \end{macro}
%
% \begin{macrocode}
%</2ekernel>
%<*2ekernel|latexrelease>
%<latexrelease>\IncludeInRelease{2022/06/01}%
%<latexrelease> {\Ref}{Add starred version}%
% \end{macrocode}
Expand Down Expand Up @@ -432,6 +485,16 @@
% \begin{macrocode}
%</2ekernel|latexrelease>
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{0000/00/00}%
%<latexrelease> {\label}{store five label arguments}%
%<latexrelease>\let\@currenttitle\@undefined
%<latexrelease>\let\@currenttarget\@undefined
%<latexrelease>\let\@kernel@currentdata\@undefined
%<latexrelease>\def\label#1{\@bsphack
%<latexrelease> \protected@write\@auxout{}%
%<latexrelease> {\string\newlabel{#1}{{\@currentlabel}{\thepage}}}%
%<latexrelease> \@esphack}
%<latexrelease>\EndIncludeInRelease
%<latexrelease>\IncludeInRelease{2020/10/01}%
%<latexrelease> {\Ref}{Add starred version}%
%<latexrelease>\def\@currentcounter{}
Expand Down
1 change: 1 addition & 0 deletions base/testfiles-lthooks/ltcmdhooks-001.tlg
Expand Up @@ -81,6 +81,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
1 change: 1 addition & 0 deletions base/testfiles-lthooks/lthooks-000.tlg
Expand Up @@ -21,6 +21,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
3 changes: 3 additions & 0 deletions base/testfiles-lthooks/lthooks-001.tlg
Expand Up @@ -27,6 +27,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down Expand Up @@ -186,6 +187,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -240,6 +242,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
3 changes: 3 additions & 0 deletions base/testfiles-lthooks/lthooks-002.tlg
Expand Up @@ -27,6 +27,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down Expand Up @@ -188,6 +189,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -242,6 +244,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
2 changes: 2 additions & 0 deletions base/testfiles-lthooks/lthooks-003.tlg
Expand Up @@ -42,6 +42,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -107,6 +108,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
2 changes: 2 additions & 0 deletions base/testfiles-lthooks/lthooks-004.tlg
Expand Up @@ -32,6 +32,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -91,6 +92,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
2 changes: 2 additions & 0 deletions base/testfiles-lthooks/lthooks-005.tlg
Expand Up @@ -49,6 +49,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -114,6 +115,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
2 changes: 2 additions & 0 deletions base/testfiles-lthooks/lthooks-006.tlg
Expand Up @@ -30,6 +30,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -87,6 +88,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
3 changes: 3 additions & 0 deletions base/testfiles-lthooks/lthooks-007.tlg
Expand Up @@ -30,6 +30,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -88,6 +89,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down Expand Up @@ -245,6 +247,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
2 changes: 2 additions & 0 deletions base/testfiles-lthooks/lthooks-008.tlg
Expand Up @@ -32,6 +32,7 @@ The sequence \g__hook_all_seq contains the items (without outer braces):
> {bfseries/defaults}
> {mdseries}
> {mdseries/defaults}
> {label}
> {enddocument}
> {enddocument/afterlastpage}
> {enddocument/afteraux}
Expand Down Expand Up @@ -86,6 +87,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Code labels for sorting:
label1, label2 and mypackage
Expand Down
1 change: 1 addition & 0 deletions base/testfiles-lthooks/lthooks-009.tlg
Expand Up @@ -27,6 +27,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
4 changes: 4 additions & 0 deletions base/testfiles-lthooks/lthooks-011.tlg
Expand Up @@ -22,6 +22,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down Expand Up @@ -177,6 +178,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down Expand Up @@ -334,6 +336,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down Expand Up @@ -493,6 +496,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down
1 change: 1 addition & 0 deletions base/testfiles-lthooks/lthooks-013.tlg
Expand Up @@ -77,6 +77,7 @@ Update code for hook 'bfseries' on input line ...:
Update code for hook 'bfseries/defaults' on input line ...:
Update code for hook 'mdseries' on input line ...:
Update code for hook 'mdseries/defaults' on input line ...:
Update code for hook 'label' on input line ...:
Update code for hook 'enddocument' on input line ...:
Update code for hook 'enddocument/afterlastpage' on input line ...:
Update code for hook 'enddocument/afteraux' on input line ...:
Expand Down