summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/hyperref/xr-hyper.dtx
blob: aced2ac70b278663ab97a003d2c516dd53326f2c (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
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-05-23 v7.01i 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
%