summaryrefslogtreecommitdiff
path: root/macros/latex-dev/required/tools/xr.dtx
blob: daa0778b3632b98c2c01949fbf82271ac557a249 (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
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
% \iffalse meta-comment
%
% Copyright (C) 1993-2024
%
% 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-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>         [2024-04-10 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}  
% 
% 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
%