% \iffalse meta-comment
%
% Copyright (C) 1993-2025
%
% The LaTeX Project and any individual authors listed elsewhere
% in this file.
%
% This file is part of the Standard LaTeX `Tools Bundle'.
% -------------------------------------------------------
%
% It may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3c
% of this license or (at your option) any later version.
% The latest version of this license is in
%    https://www.latex-project.org/lppl.txt
% and version 1.3c or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% The list of all files belonging to the LaTeX `Tools Bundle' is
% given in the file `manifest.txt'.
%
% \fi
% \iffalse
%% File: xr.dtx Copyright (C) 1993-2025 David Carlisle
%
%<package>\NeedsTeXFormat{LaTeX2e}
%<package>\DeclareRelease{v5}{2023-07-04}{xr-2023-07-04.sty}
%<package>\DeclareCurrentRelease{}{2024-12-22}
%<package>\ProvidesPackage{xr}
%<package>         [2024-12-22 v6.00 eXternal References (DPC)]
%
%<*driver>
\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}
\title{The \textsf{xr} package\thanks{This file
        has version number \fileversion, last
        revised \filedate.}}
\author{David Carlisle\thanks{%
  The Author of Versions 1--4 was Jean-Pierre Drucbert}}
\date{\filedate}
\MaintainedByLaTeXTeam{tools}
\maketitle
\DocInput{xr.dtx}
\end{document}
%</driver>
% \fi
%
% %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
%
% \changes{v5.00}{1993/07/07}
%         {First DPC version (by agreement with J-PD).  New mechanism
%         (\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 \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| (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 \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 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}
%
% Problems with citing references from an external document
% are more likely if the documents are using different citation packages.
% So if possible, it is best to ensure that the documents use compatible
% packages so that the citation data works without error when imported from
% the external document.
% 
% 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{}
%
% \section{The macros}
%
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% Check for the optional argument.
% \changes{v6.00}{2024-04-10}{Copied over extended definition of xr-hyper}
%    \begin{macrocode}
\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{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#3[#4]{{%
  \makeatletter
  \def\XR@prefix{#1}%
   \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
% the list of files to process.
%    \begin{macrocode}
\def\XR@next#1\relax#2\\{%
  \edef\XR@list{#2}%
  \XR@loop{#1}}
%    \end{macrocode}
%
% Check whether the list of |aux| files is empty.
%    \begin{macrocode}
\def\XR@aux{%
  \ifx\XR@list\@empty\else\expandafter\XR@explist\fi}
%    \end{macrocode}
%

% Expand the list of aux files, and call |\XR@next| to process the first
% one.
%    \begin{macrocode}
\def\XR@explist{\expandafter\XR@next\XR@list\\}
%    \end{macrocode}
%
% If the |aux| file exists, loop through line by line, looking for
% |\newlabel| and |\@input|. Otherwise process the next file in the
% list.
%  \changes{v5.06}{2020-05-10}{Add braces around the filename to
%    support filenames with spaces (gh/223)}
%    \begin{macrocode}
\def\XR@loop#1{\openin\@inputcheck{#1}\relax
  \ifeof\@inputcheck
    \PackageWarning{xr}{^^JNo file #1^^JLABELS NOT IMPORTED.^^J}%
    \expandafter\XR@aux
  \else
    \PackageInfo{xr}{IMPORTING LABELS FROM #1}%
    \expandafter\XR@read\fi}
%    \end{macrocode}
%
% Read the next line of the aux file.
%    \begin{macrocode}
\def\XR@read{%
  \read\@inputcheck to\XR@line
%    \end{macrocode}
% The |...| make sure that |\XR@test| always has sufficient arguments.
%    \begin{macrocode}
  \expandafter\XR@test\XR@line...\XR@}
%    \end{macrocode}
%
% Look at the first token of the line.
% 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\@gobblefour
  \ifx#1\newlabel
    \let\XR@tempa\@firstoffour
  \else\ifx#1\XR@bibcite
    \let\XR@tempa\@secondoffour
  \else\ifx#1\@input
     \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}
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
%
