summaryrefslogtreecommitdiff
path: root/macros/latex-dev/required/tools/xr.dtx
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex-dev/required/tools/xr.dtx')
-rw-r--r--macros/latex-dev/required/tools/xr.dtx229
1 files changed, 202 insertions, 27 deletions
diff --git a/macros/latex-dev/required/tools/xr.dtx b/macros/latex-dev/required/tools/xr.dtx
index 3914cebcd9..daa0778b36 100644
--- a/macros/latex-dev/required/tools/xr.dtx
+++ b/macros/latex-dev/required/tools/xr.dtx
@@ -21,14 +21,49 @@
%
% \fi
% \iffalse
-%% File: xr.dtx Copyright (C) 1993-2019 David Carlisle
+%% File: xr.dtx Copyright (C) 1993-2024 David Carlisle
%
%<package>\NeedsTeXFormat{LaTeX2e}
+%<package>\DeclareRelease{v5}{2023-07-04}{xr-2023-07-04.sty}
+%<package>\DeclareCurrentRelease{}{2024-04-10}
%<package>\ProvidesPackage{xr}
-%<package> [2023-07-04 v5.06 eXternal References (DPC)]
+%<package> [2024-04-10 v6.00 eXternal References (DPC)]
%
%<*driver>
-\documentclass{ltxdoc}
+\documentclass{l3doc}
+% currently missing in l3doc, copied from array.dtx
+\makeatletter
+\def\MaintainedBy#1{\gdef\@maintainedby{#1}}
+\let\@maintainedby\@empty
+\def\MaintainedByLaTeXTeam#1{%
+{\gdef\@maintainedby{%
+This file is maintained by the \LaTeX{} Project team.\\%
+Bug reports can be opened (category \texttt{#1}) at\\%
+\url{https://latex-project.org/bugs.html}.}}}
+\def\@maketitle{%
+ \newpage
+ \null
+ \vskip 2em%
+ \begin{center}%
+ \let \footnote \thanks
+ {\LARGE \@title \par}%
+ \vskip 1.5em%
+ {\large
+ \lineskip .5em%
+ \begin{tabular}[t]{c}%
+ \@author
+ \end{tabular}\par}%
+ \vskip 1em%
+ {\large \@date}%
+ \ifx\@maintainedby\@empty
+ \else
+ \vskip 1em%
+ \fbox{\fbox{\begin{tabular}{@{}l@{}}\@maintainedby\end{tabular}}}%
+ \fi
+ \end{center}%
+ \par
+ \vskip 1.5em}
+\makeatother
\usepackage{xr}
\GetFileInfo{xr.sty}
\begin{document}
@@ -50,44 +85,113 @@
%
% \changes{v5.00}{1993/07/07}
% {First DPC version (by agreement with J-PD). New mechanism
-% (\cmd{\read} instead of \cmd\input).}
+% (\cs{read} instead of \cs{input}).}
%
% \changes{v5.01}{1993/07/20}{Fix bug added by DPC, v5.00 did not import
-% aux files of \cmd\include'ed files. (Reported by J-PD)}
+% aux files of \cs{include}'ed files. (Reported by J-PD)}
%
% \changes{v5.02}{1994/05/28}{Update for LaTeX2e}
% \changes{v5.03}{2018/10/01}{Fix for conditionals in aux file}
% \changes{v5.05}{2019/07/20}{include xcite}
+% \changes{v6.00}{2024/04/10}{merge with xr-hyper}
%
%
% This package implements a system for eXternal References.
-%
+% Version 6.00 merges the \pkg{xr} package and the \pkg{xr-hyper} package.
+% \pkg{xr-hyper} was developed to support the
+% extended label syntax of the \pkg{hyperref} package and to enable active links
+% to the external documents.
+% In the \LaTeX{} release 2023-06-01 the label syntax of \pkg{hyperref}
+% and the \LaTeX{} kernel have been synchronized and there is no longer
+% a need for two packages. The package \pkg{xr-hyper} will be
+% deprecated.
+%
+% The previous version before the merge can be accessed with
+% \begin{verbatim}
+% \usepackage{xr}[=v5]
+% \end{verbatim}
+% or with a rollback date between 2023-07-04 and 2024-04-09
+% \begin{verbatim}
+% \usepackage{xr}[=2024-04-09]
+% \end{verbatim}
+%
+% \section{Usage}
+%
+% \begin{syntax}
+% \cs{externaldocument}\oarg{prefix}\texttt[nocite\texttt]\marg{document}\oarg{url}
+% \end{syntax}
+%
% If one document needs to refer to sections of another, say |aaa.tex|,
% then this package may be loaded in the main file, and the command\\
% |\externaldocument{aaa}|\\
% given in the preamble.
%
-% Then you may use |\ref| and |\pageref| to refer to anything which has
+% Then you may use |\ref| and |\pageref| (or |\nameref| if the
+% package \pkg{nameref} has been loaded to refer to anything which has
% been given a |\label| in either |aaa.tex| or the main document.
+% It is also possible to refer to properties stored with \cs{RecordProperties}.
% You may declare any number of such external documents.
%
% If any of the external documents, or the main document, use the same
% |\label| then an error will occur as the label will be multiply
% defined. To overcome this problem |\externaldocument| has an optional
-% argument. If you declare |\externaldocument[A-]{aaa}|, then all
+% argument \meta{prefix}.
+% If you declare |\externaldocument[A-]{aaa}|, then all
% references from |aaa| are prefixed by |A-|. So for instance, if a
% section of |aaa| had |\label{intro}|, then this could be referenced
% with |\ref{A-intro}|. The prefix need not be |A-|, it can be any
% string chosen to ensure that all the labels imported from external
-% files are unique. Note however that if your style declares certain
-% active characters (|:| in French, |"| in German) then these
-% characters can not usually be used in |\label|, and similarly may not
-% be used in the optional argument to |\externaldocument|.
+% files are unique. Note however that the prefix is expanded and
+% so should not contain commands that are not safe in this context.
%
% As first suggested in Enrico Gregorio's |xcite| package, the current version
% also allows |\cite| to reference |\bibitem| in the external document.
% For compatibility with |xcite|, |\externalcitedocument| is made available
% as an alias for |\externaldocument|
+%
+% Many packages have variant citation commands (natbib,
+% biblatex,....) and the external document may or may not have used
+% hyperref. Because of these differences the citation linking may not
+% always work, it can be disabled by specifying \texttt{[nocite]} after the
+% \meta{prefix}:
+% \begin{verbatim}
+% \externaldocument[][nocite]{aaa}
+% \end{verbatim}
+%
+% The `document' referred to by the main argument \meta{document} is the file
+% \file{document.aux} which must be somewhere on TeX's input path.
+% Some packages (eg hyperref) really need to know the location of the
+% final document rather than the aux file. By default this is assumed
+% to be \file{document.pdf}. A package may redefine the command \cs{XR@ext} to
+% change this default extension. However sometimes the final
+% document may be in a position unrelated to the aux file, or the
+% browser may not be able to find files at an arbitrary point in
+% TeX's input path, so the final optional argument \meta{url} allows a full
+% URL to the final document to be specified.
+% \begin{verbatim}
+% \externaldocument{aaa}[https://example.com/this/path/to/aaa.pdf]
+% \end{verbatim}
+%
+% The package stores the url of the external document in the label data. It can
+% e.g. be retrieved with the \pkg{refcount} package
+%
+% \begin{verbatim}
+% \usepackage{refcount,xr}
+% \externaldocument{aaa}
+% ...
+% \getrefbykeydefault{intro}{url}{??} %prints aaa.pdf or ??
+% \end{verbatim}
+%
+% \pkg{xr} supports also the properties introduced in \LaTeX{} 2023-11-01.
+% Here the url of the external document is stored in the \texttt{xr-url} property.
+%
+% \begin{verbatim}
+% \usepackage{xr}
+% \externaldocument{aaa} %aaa contains \RecordProperties{intro}{page}
+% ...
+% \RefProperty{intro}{page} %gives page number
+% \RefProperty{intro}{xr-url} %gives aaa.pdf
+% \end{verbatim}
%
% \MaybeStop{}
%
@@ -98,20 +202,74 @@
% \end{macrocode}
%
% Check for the optional argument.
+% \changes{v6.00}{2024-04-10}{Copied over extended definition of xr-hyper}
% \begin{macrocode}
-\def\externaldocument{\@ifnextchar[\XR@{\XR@[]}}
+\def\externaldocument{\@testopt\XR@cite{}}
\let\externalcitedocument\externaldocument
+\def\XR@cite[#1]{\@testopt{\XR@[#1]}{}}
+\def\XR@[#1][#2]#3{\@testopt{\XR@@{#1}{#2}{#3}}{#3.\XR@ext}}
+% \end{macrocode}
+%
+% \subsection{helper definitions}
+% \changes{v6.00}{2024-04-10}{new, copied over from xr-hyper}
+% To test the second optional argument
+% \begin{macrocode}
+\def\XR@@nocite{nocite}
+% \end{macrocode}
+% Needed in the processing
+% \begin{macrocode}
+\long\def\@gobblefour #1#2#3#4{}
+\long\def\@firstoffour #1#2#3#4{#1}
+\long\def\@secondoffour#1#2#3#4{#2}
+\long\def\@thirdoffour #1#2#3#4{#3}
+\long\def\@fourthoffour #1#2#3#4{#4}
+% \end{macrocode}
+% The url is added as fifth argument. The command used here is
+% \cs{XR@addURL}. The command is more complicated as needed
+% as it tries to handle also older documents with
+% \cs{newlabel}'s with two arguments.
+% \begin{macrocode}
+\def\XR@addURL#1{\XR@@dURL#1{}{}{}{}\\}
+\def\XR@@dURL#1#2#3#4#5\\{%
+ \unexpanded{{#1}{#2}{#3}{#4}}{\XR@URL}%
+ }%
+% \end{macrocode}
+%
+% \subsection{Variables}
+% \changes{v6.00}{2024-04-10}{new, copied over from xr-hyper}
+% Default file extension:
+% \begin{macrocode}
+\providecommand\XR@ext{pdf}
% \end{macrocode}
%
-% Save the optional prefix. Start processing the first |aux| file.
-% \changes{v5.06}{2020-05-10}{Remove leading and trailing sapces from
+% Save the optional prefix. Start processing the first |aux| file.
+% \changes{v6.00}{2024-04-10}{copied over the new extended internal command from xr-hyper.
+% It prepends the directory name.}
+% Olivier Michel pointed out that
+% if the aux file was not on texinputs you could not always go
+% \cs{externaldocument}{/some/path/to/file}
+% specifically that worked if file.aux was a `simple' document with
+% one aux file, but if \cs{include} had been used, the `sub' aux files
+% would not be found by xr in the remote directory.
+% This version calls \cs{filename@parse} to get the directory name of the
+% remote directory, which is then explicitly prepended to the names of
+% any included aux files.
+% \changes{v5.06}{2020-05-10}{Remove leading and trailing spaces from
% the filename (gh/2223)}
% \begin{macrocode}
-\def\XR@[#1]#2{{%
+\def\XR@@#1#2#3[#4]{{%
\makeatletter
\def\XR@prefix{#1}%
- \set@curr@file{#2}%
- \expandafter\XR@next\@curr@file.aux\relax\\}}
+ \def\XR@nocite{#2}%
+ \ifx\XR@nocite\XR@@nocite
+ \let\XR@bibcite\vadjust
+ \else
+ \let\XR@bibcite\bibcite
+ \fi
+ \def\XR@URL{#4}%
+ \set@curr@file{#3}%
+ \filename@parse\@curr@file
+ \XR@next\@curr@file.aux\relax\\}}
% \end{macrocode}
%
% Process the next |aux| file in the list and remove it from the head of
@@ -161,23 +319,40 @@
% \end{macrocode}
%
% Look at the first token of the line.
-% If it is |\newlabel|, do the |\newlabel|. If it is |\@input|, add the
-% filename to the list of files to process. Otherwise ignore.
+% If it is |\newlabel|, define \cs{r@}\meta{label}, ensure that it has
+% five label data argument and add the url as the last one.
+% If it is |\@input|, add the
+% filename to the list of files to process.
+% If it is |\bibcite|, call a |\bibcite|.
+% If it is |\new@label@record| add the url and then call it.
+% Otherwise ignore.
% Go around the loop if not at end of file. Finally process the next
% file in the list.
%
% 2018 update: make sure the arguments are handled outside the |\ifx| test,
+% \changes{v6.00}{2024-04-10}{copied over extended definition from xr-hyper}
% \begin{macrocode}
\long\def\XR@test#1#2#3#4\XR@{%
- \let\XR@tempa\@gobbletwo
+ \let\XR@tempa\@gobblefour
\ifx#1\newlabel
- \let\XR@tempa\@firstoftwo
- \else\ifx#1\bibcite
- \let\XR@tempa\@firstoftwo
+ \let\XR@tempa\@firstoffour
+ \else\ifx#1\XR@bibcite
+ \let\XR@tempa\@secondoffour
\else\ifx#1\@input
- \let\XR@tempa\@secondoftwo
- \fi\fi\fi
- \XR@tempa{#1{\XR@prefix#2}{#3}}{\edef\XR@list{\XR@list#2\relax}}%
+ \let\XR@tempa\@thirdoffour
+ \else\ifx#1\new@label@record
+ \let\XR@tempa\@fourthoffour
+ \fi\fi\fi\fi
+ \XR@tempa
+ {%
+ \expandafter\protected@xdef\csname r@\XR@prefix#2\endcsname{\XR@addURL{#3}}%
+ }%
+ {\expandafter\bibcite\expandafter{\XR@prefix#2}{#3}}%
+ {\edef\XR@list{\XR@list\filename@area#2\relax}}%
+ {%
+ \edef\next{\noexpand\new@label@record{\XR@prefix#2}{\unexpanded{#3}{xr-url}{\XR@URL}}}%
+ \next
+ }
\ifeof\@inputcheck\expandafter\XR@aux
\else\expandafter\XR@read\fi}
% \end{macrocode}