diff options
Diffstat (limited to 'macros/latex/contrib/hyperref/xr-hyper.dtx')
-rw-r--r-- | macros/latex/contrib/hyperref/xr-hyper.dtx | 348 |
1 files changed, 348 insertions, 0 deletions
diff --git a/macros/latex/contrib/hyperref/xr-hyper.dtx b/macros/latex/contrib/hyperref/xr-hyper.dtx new file mode 100644 index 0000000000..1acb21c688 --- /dev/null +++ b/macros/latex/contrib/hyperref/xr-hyper.dtx @@ -0,0 +1,348 @@ +% \iffalse meta-comment +% +% Copyright (C) 1993-2024 David Carlisle +% +% This file is part of the `Hyperref Bundle'. +% ------------------------------------------- +% +% This work may be distributed and/or modified under the +% conditions of the LaTeX Project Public License, either version 1.3 +% of this license or (at your option) any later version. +% The latest version of this license is in +% http://www.latex-project.org/lppl.txt +% and version 1.3 or later is part of all distributions of LaTeX +% version 2005/12/01 or later. +% +% This work has the LPPL maintenance status `maintained'. +% +% The Current Maintainer of this work is the LaTeX Project. +% +% The list of all files belonging to the `Hyperref Bundle' is +% given in the file `manifest.txt'. +% +% \fi +% \iffalse +%% File: xr-hyper.dtx Copyright (C) 1993-2024 David Carlisle +% +%<package>\NeedsTeXFormat{LaTeX2e} +%<package>\ProvidesPackage{xr-hyper} +%<package> [2024-01-20 v7.01h eXternal References (DPC)] +% +%<*driver> +\documentclass{l3doc} +\usepackage{xr-hyper} +\GetFileInfo{xr-hyper.sty} +\begin{document} +\title{The \textsf{xr-hyper} package\thanks{This file + has version number \fileversion, last + revised \filedate.}} +\author{David Carlisle} +\date{\filedate} +\maketitle +\DocInput{xr-hyper.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}). (xr)} +% +% \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) (xr)} +% +% \changes{v5.02}{1994/05/28}{Update for LaTeX2e} +% \changes{v5.03}{2018/10/01}{Fix for conditionals in aux file (xr)} +% \changes{v5.05}{2019/07/20}{include xcite (xr)} +% +% \changes{v6.00 beta2}{1997/10/06} +% {} +% +% \changes{v6.00 beta3}{1999/09/01} +% {Definitions of \cs{XR@addURL} corrected (Heiko Oberdiek)} +% +% \changes{v6.00 beta 4}{2000/03/22} +% {\cmd\xdef changed to \cs{protected@xdef}} +% +% \changes{v6.1}{2019/10/03} +% {Incorporate updates to \pkg{xr} (including citation support)} +% +% \changes{v7.00e}{2020-05-14} +% {add additional braces to \cs{r@}\meta{label} only if \pkg{hyperref} is not detected in the aux +% of the source document (https://github.com/latex3/hyperref/issues/118)} +% +% \changes{v7.00z}{2023-05-15} +% {unified and simplified the brace handling: all defined references have now +% five brace groups. Together with the planed change in LaTeX 2023-06-01 this +% will improve the combination of hyperref/non-hyperref documents.} +% +% \changes{v7.01g}{2023-11-26} +% {Always store the URL/file name of the external document to allow file links +% even if it has no destinations.} +% +% \changes{v7.01h}{2024-01-20} +% {do not expand the labels when reading, (https://github.com/latex3/hyperref/issues/327)} +% +% \changes{v7.01h}{2024-01-20} +% {support \LaTeX\ properties.} +% +% This package implements a system for eXternal References. +% +% It is an extension of the \pkg{xr} package. It 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. \pkg{xr-hyper} already works with all documents -- +% it is not required to load\pkg{hyperref} -- and its code will move in the +% next \LaTeX{} release into the \pkg{xr} package. Then \pkg{xr-hyper} can be +% deprecated. +% +% \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 +% \begin{verbatim} +% |\externaldocument{aaa}| +% \end{verbatim} +% 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. +% 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} +% +% 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}[http://here.xxx.edu/this/path/to/aaa.pdf] +% \end{verbatim} +% +% The package stores the url of the external document in the label data. If can +% e.g. be retrieved with the \pkg{refcount} package +% +% \begin{verbatim} +% \usepackage{refcount,xr-hyper} +% \externaldocument{aaa} +% ... +% \getrefbykeydefault{intro}{url}{??} %prints aaa.pdf or ?? +% \end{verbatim} +% +% \pkg{xr-hyper} 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-hyper} +% \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. +% \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} +% 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} +% +% Default file extension: +% \begin{macrocode} +\providecommand\XR@ext{pdf} +% \end{macrocode} +% +% \subsection{Processing} +% Save the optional prefix. Start processing the first |aux| file. +% Version beta2 also added another improvement unrelated +% to the hyperref support. 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 sapces from +% the filename (gh/2223) (xr)} +% \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) (xr)} +% \changes{v7.01h}{2024-01-20}{Add braces around the filename to +% support filenames with spaces (gh/223) similar to xr} +% \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. +% Make sure the arguments are handled outside the |\ifx| test, +% \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 +% |