diff options
Diffstat (limited to 'macros/latex-dev/required/tools/xr.dtx')
-rw-r--r-- | macros/latex-dev/required/tools/xr.dtx | 229 |
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} |