Debian Codegraph @

texmf-dist/source/latex/hyper/backcite.dtx

raw
1 % \iffalse
2 %% File: backcite.dtx Copyright (C) 1995--1999 Michael Mehlich
3 %% This program can be redistributed and/or modified under the terms
4 %% of the LaTeX Project Public License Distributed from CTAN
5 %% archives in directory macros/latex/base/lppl.txt; either
6 %% version 1 of the License, or any later version.
7 %
8 %<*driver>
9 \documentclass{ltxdoc}
10 \IfFileExists{hyper.sty}{%
11 \message{*** Generating hypertext documentation ***}
12 \usepackage[color,pagetop]{hyper}%
13 }{%
14 \def\hyperURL##1##2##3##4{##4}
15 }
16 %</driver>
17 \def\fileversion{V2.0}
18 \def\filedate{1997/03/01}
19 \def\docdate{1997/03/01}
20 %<*driver>
21 \begin{document}
22 \title{Backcite Extension for Hyper\LaTeXe\\\fileversion}
23 \author{Michael Mehlich}
24 \date{\docdate}
25 \maketitle
26 \tableofcontents
27 \DocInput{backcite.dtx}
28 \end{document}
29 %</driver>
30 % \fi
31 % \CheckSum{513}
32 %%
33 %% \CharacterTable
34 %% {Upper-case \A\B\C\D\E\F\G\H\I\J\K\L\M\N\O\P\Q\R\S\T\U\V\W\X\Y\Z
35 %% Lower-case \a\b\c\d\e\f\g\h\i\j\k\l\m\n\o\p\q\r\s\t\u\v\w\x\y\z
36 %% Digits \0\1\2\3\4\5\6\7\8\9
37 %% Exclamation \! Double quote \" Hash (number) \#
38 %% Dollar \$ Percent \% Ampersand \&
39 %% Acute accent \' Left paren \( Right paren \)
40 %% Asterisk \* Plus \+ Comma \,
41 %% Minus \- Point \. Solidus \/
42 %% Colon \: Semicolon \; Less than \<
43 %% Equals \= Greater than \> Question mark \?
44 %% Commercial at \@ Left bracket \[ Backslash \\
45 %% Right bracket \] Circumflex \^ Underscore \_
46 %% Grave accent \` Left brace \{ Vertical bar \|
47 %% Right brace \} Tilde \~}
48 %%
49 % \MakeShortVerb{|}
50 %
51 % \title{Hyper\LaTeXe}
52 % \maketitle
53 %
54 % \section{Introduction}
55 % For developing documents it is often useful to know the places
56 % bibliographic entries have been used in. This subpackage of
57 % the |hyper|--package realizes this by remembering the pages
58 % or sections/theorems and so on a |\cite| command occurs in.
59 % The resulting informations are then added to the respectively
60 % bibliograhic entries for the citations.
61 %
62 % \section{Usage}
63 % This package is not intended to be used stand alone but only
64 % together with the |hyper|--package. You can invoke it by giving
65 % |backcitepages| respectively |backcitesections| as optional
66 % parameters for the |hyper|--package.
67 %
68 % \StopEventually{}
69 %
70 % \clearpage
71 % \section{The Realization}
72 % First of all, introduce the standard header.
73 % \begin{macrocode}
74 %<*backcite>
75 \NeedsTeXFormat{LaTeX2e}[1995/12/01]
76 \ProvidesPackage{hxt-bc}%
77 [\filedate\space Backcite extension for HyperLaTeX2e]
78 % \end{macrocode}
79 % Now check whether the |\hyper|--package already has been loaded.
80 % Otherwise, print a warning message and load it.
81 % \begin{macrocode}
82 \@ifpackageloaded{hyper}{}{%
83 \PackageWarningNoLine{backcite}{%
84 Backcite extension of hyper package needs hyper package.\MessageBreak
85 Loading hyper package.%
86 }%
87 \usepackage[no]{hyper}%
88 }
89 % \end{macrocode}
90 % We have to recognize all the places for the citations; thus, we need a
91 % collector for them that introduces a new macro holding this information
92 % for each cite and, to check them being unchanged by a latex run, a new
93 % token list holding all these macros. Such a collector is defined
94 % in a generic way by the following macro. (First time I used
95 % |\expandafter| seven(!) times one after another.)
96 % \begin{macrocode}
97 \def\hyper@aux#1#2#3{%
98 \expandafter\ifx\csname hyper@aux@#1@#2\endcsname\relax%
99 \expandafter\global%
100 \expandafter\edef\csname hyper@aux@#1@#2\endcsname%
101 {(#3)}%
102 \else%
103 \expandafter\global%
104 \expandafter\edef\csname hyper@aux@#1@#2\endcsname%
105 {\csname hyper@aux@#1@#2\endcsname(#3)}%
106 \fi%
107 \expandafter\ifx\csname hyper@aux@#1\endcsname\relax%
108 \expandafter\global\expandafter%
109 \newtoks\csname hyper@aux@#1\endcsname%
110 \fi%
111 \def\hyper@tempa{\csname hyper@aux@#1\endcsname}%
112 \expandafter\expandafter\expandafter\expandafter%
113 \expandafter\expandafter\expandafter\global%
114 \expandafter\expandafter\expandafter\expandafter%
115 \expandafter\expandafter\expandafter\hyper@tempa%
116 \expandafter\expandafter\expandafter\expandafter%
117 \expandafter\expandafter\expandafter{%
118 \expandafter\expandafter\expandafter\the\expandafter\hyper@tempa%
119 \csname hyper@aux@#1@#2\endcsname%
120 }%
121 }
122 % \end{macrocode}
123 % To remember the citations between two runs or realize a bibliography in
124 % front of a document we have to write the neccessary informations about
125 % the occurrences of the citations to the axiliary file and get the
126 % informations back when reading this file during startup.\newline
127 % Damned, why do different packages handle this differently?
128 % \begin{macrocode}
129 \def\hyperbackcite#1#2#3#4{\hyper@aux{br}{#1}{#2,#3,#4}}
130 \def\hyper@back@to@aux#1{%
131 \@bsphack%
132 \protected@write%
133 \@auxout%
134 {}%
135 {\string\hyperbackcite%
136 {#1}%
137 {\@currenthyper}%
138 {\@currentlabel}%
139 {\thepage}%
140 }%
141 \@esphack%
142 }
143 \def\hyper@back@to@aux@list#1{%
144 \@for\@citeb:=#1\do%
145 {\edef\@citeb{\expandafter\@firstofone\@citeb}%
146 \@bsphack%
147 \protected@write%
148 \@auxout%
149 {}%
150 {\string\hyperbackcite%
151 {\@citeb}%
152 {\@currenthyper}%
153 {\@currentlabel}%
154 {\thepage}%
155 }%
156 \@esphack%
157 }%
158 }
159 \let\hyper@citex\@citex%
160 \def\@citex[#1]#2{%
161 \hyper@back@to@aux@list{#2}%
162 \hyper@citex[#1]{#2}%
163 }%
164 \ifx\harvarditem\@undefined\else%
165 \let\hyper@har@citetoaux\HAR@citetoaux%
166 \def\HAR@citetoaux#1{%
167 \hyper@back@to@aux{#1}%
168 \hyper@har@citetoaux{#1}%
169 }%
170 \fi
171 \ifx\NAT@set@cites\@undefined\else%
172 \let\hyper@hyper@natlinkstart\hyper@natlinkstart%
173 \def\hyper@natlinkstart#1#2\hyper@natlinkend{%
174 \hyper@back@to@aux{#1}%
175 \hyper@hyper@natlinkstart{#1}{#2}\hyper@natlinkend%
176 }%
177 \ifnum\NAT@sort=1\relax
178 \let\hyper@back@hold\relax
179 \def\hyper@compress@cite#1#2{%
180 \advance\@tempcnta\@ne%
181 \ifnum #1=\@tempcnta%
182 \ifx\@h@ld\relax%
183 \edef\@h@ld{%
184 \@citea%
185 \noexpand%
186 \hyper@natlinkstart{#2}{#1}%
187 \noexpand%
188 \hyper@natlinkend%
189 }%
190 \def\hyper@back@hold{\hyper@back@to@aux{#2}}%
191 \else%
192 \hyper@back@hold%
193 \def\@h@ld{%
194 \hbox{--}%
195 \hyper@natlinkstart{#2}{#1}\hyper@natlinkend%
196 }%
197 \def\hyper@back@hold{\hyper@back@to@aux{#2}}%
198 \fi%
199 \else%
200 \@h@ld\@citea%
201 \hyper@natlinkstart{#2}{#1}\hyper@natlinkend%
202 \let\@h@ld\relax%
203 \fi%
204 \@tempcnta#1\def\@citea{\NAT@sep\penalty\@m\NAT@space}%
205 }
206 \fi
207 \NAT@set@cites
208 \fi%
209 % \end{macrocode}
210 % However, that does not help much. So far we did not write the informations
211 % down into the resulting |dvi|--file. To overcome this we modify
212 % the |\bibitem|--command such that the respectively informations will be
213 % added after each entry.
214 % \begin{macrocode}
215 \let\hyper@lbibitem\@lbibitem
216 \def\@lbibitem[#1]#2#3\par{%
217 \hyper@lbibitem[#1]{#2}#3%
218 \expandafter\hyper@backcite\csname hyper@aux@br@#2\endcsname%
219 \par%
220 }
221 \let\hyper@bibitem\@bibitem
222 \def\hyper@bibitem#1#2\par{%
223 \hyper@bibitem{#1}#2%
224 \expandafter\hyper@backcite\csname hyper@aux@br@#1\endcsname%
225 \par%
226 }
227 \ifx\harvarditem\@undefined\else
228 \let\hyper@harvarditem\harvarditem
229 \def\harvarditem{%
230 \@ifnextchar[{\hyper@harvard@oitem}{\hyper@harvard@item}%
231 }
232 \def\hyper@harvard@item#1#2#3#4\par{%
233 \hyper@harvarditem{#1}{#2}{#3}#4%
234 \expandafter\hyper@backcite\csname hyper@aux@br@#3\endcsname%
235 \par%
236 }
237 \def\hyper@harvard@oitem[#1]#2#3#4#5\par{%
238 \hyper@harvarditem[#1]{#2}{#3}{#4}#5%
239 \expandafter\hyper@backcite\csname hyper@aux@br@#4\endcsname%
240 \par%
241 }
242 \fi
243 % \end{macrocode}
244 % As we do not want an entry several times\footnote{Note, that currently
245 % we do not sort the list of informations. Thus, we may get several
246 % identical entries for the sectioning informations if, e.g.\ we cite
247 % something within a theorem.}
248 % but want to insert a hint
249 % about the type of backcites, we have to count then number of informations
250 % for each citation.
251 % Afterwards we can print out this hint and loop through all informations
252 % to print them out.
253 % \begin{macrocode}
254 \def\hyperbackcitepage{Cited on page~}
255 \def\hyperbackcitepages{Cited on pages~}
256 \def\hyperbackcitesection{Cited in~}
257 \def\hyperbackcitesections{Cited in~}
258 \def\hyperbackcitenormalseparator{, }
259 \def\hyperbackcitefinalseparatorpair{ and~}
260 \def\hyperbackcitefinalseparatorlist{, and~}
261 \def\hyper@backcite#1{%
262 \bgroup%
263 \let\hyper@last@cite\relax%
264 \count11=0\relax%
265 \expandafter\hyper@back@cnt#1\relax%
266 \let\hyper@last@cite\relax%
267 \expandafter\ifnum\count11>0\relax%
268 \if@hyper@back@pages@%
269 \expandafter\ifnum\count11>1\relax%
270 \hyperbackcitepages%
271 \else%
272 \hyperbackcitepage%
273 \fi%
274 \else%
275 \expandafter\ifnum\count11>1\relax%
276 \hyperbackcitesection%
277 \else%
278 \hyperbackcitesections%
279 \fi%
280 \fi%
281 \ifnum\count11>2\relax%
282 \let\hyper@back@final@connection%
283 \hyperbackcitefinalseparatorlist%
284 \else%
285 \let\hyper@back@final@connection%
286 \hyperbackcitefinalseparatorpair%
287 \fi%
288 \expandafter\hyper@@backcite#1\relax.%
289 \fi%
290 \egroup%
291 }
292 \def\hyper@back@cnt{\@ifnextchar({\hyper@@back@cnt}{\@gobble}}
293 \def\hyper@@back@cnt(#1,#2,#3){%
294 \if@hyper@back@pages@%
295 \edef\hyper@tempa{#3}%
296 \ifx\hyper@last@cite\hyper@tempa\relax\else%
297 \advance\count11by1\relax%
298 \edef\hyper@last@cite{#3}%
299 \fi%
300 \else%
301 \edef\hyper@tempa{#2}%
302 \ifx\hyper@tempa\@empty%
303 \else\ifx\hyper@last@cite\hyper@tempa\relax\else%
304 \advance\count11by1\relax%
305 \edef\hyper@last@cite{#2}%
306 \fi\fi%
307 \fi%
308 \hyper@back@cnt%
309 }
310 \def\hyper@@backcite{\@ifnextchar({\hyper@@@backcite}{}}
311 \def\hyper@@@backcite(#1,#2,#3){%
312 \if@hyper@back@pages@%
313 \edef\hyper@tempa{#3}%
314 \ifx\hyper@tempa\@empty\relax%
315 \else\ifx\hyper@last@cite\hyper@tempa\relax\else%
316 \advance\count11by-1\relax%
317 \ifx\hyper@last@cite\relax\else%
318 \ifnum\count11=0\relax%
319 \hyper@back@final@connection%
320 \else%
321 \hyperbackcitenormalseparator%
322 \fi%
323 \fi%
324 \hyperpagereference{#3}{#3}%
325 \edef\hyper@last@cite{#3}%
326 \fi\fi%
327 \else%
328 \edef\hyper@tempa{#2}%
329 \ifx\hyper@tempa\@empty\relax%
330 \else\ifx\hyper@last@cite\hyper@tempa\relax\else%
331 \advance\count11by-1\relax%
332 \ifx\hyper@last@cite\relax\else%
333 \ifnum\count11=0\relax%
334 \hyper@back@final@connection%
335 \else%
336 \hyperbackcitenormalseparator%
337 \fi%
338 \fi%
339 \hyperreference{#1}{#2}%
340 \edef\hyper@last@cite{#2}%
341 \fi\fi%
342 \fi%
343 \hyper@@backcite%
344 }
345 % \end{macrocode}
346 % At the end of the latex run we want to check whether the backcites
347 % may have changed to warn the user about this problem. Thus, we
348 % reread the auxiliary file just generated and collect all the informations
349 % about the new citations. Afterwards we just check their equivalence
350 % roughly such that everything is correct at least when no warning message
351 % is printed.
352 % \begin{macrocode}
353 \def\hyperbackcite@check#1#2#3#4{\hyper@aux{brc}{#1}{#2,#3,#4}}
354 \let\hyper@back@cite@enddocument\enddocument
355 \def\enddocument{%
356 \let\hyperbackcite\hyperbackcite@check%
357 \let\hyper@@backcite@end\@@end%
358 \def\@@end{\hyper@check@backcites\hyper@@backcite@end}%
359 \hyper@back@cite@enddocument%
360 }
361 \def\hyper@check@backcites{%
362 \expandafter\ifx\csname hyper@aux@br\endcsname\relax%
363 \expandafter\ifx\csname hyper@aux@brc\endcsname\relax%
364 \else%
365 \PackageWarningNoLine{backcite}{%
366 Backcite(s) may have changed.\MessageBreak
367 Rerun to get back references right%
368 }%
369 \fi%
370 \else\expandafter\ifx\csname hyper@aux@brc\endcsname\relax%
371 \PackageWarningNoLine{backcite}{%
372 Backcite(s) may have changed.\MessageBreak
373 Rerun to get back references right%
374 }%
375 \else%
376 \edef\hyper@tempa{\the\hyper@aux@br}
377 \edef\hyper@tempb{\the\hyper@aux@brc}
378 \edef\hyper@tempa{\hyper@tempa}
379 \edef\hyper@tempb{\hyper@tempb}
380 \ifx\hyper@tempa\hyper@tempb\else%
381 \PackageWarningNoLine{backcite}{%
382 Backcite(s) may have changed.\MessageBreak
383 Rerun to get back references right%
384 }%
385 \fi%
386 \fi\fi%
387 }
388 % \end{macrocode}
389 % Now let's just introduce the options for this package, i.e.\ decide
390 % whether we want to introduce backreferences for the citations using
391 % the pages or the section/theorem numbers.
392 % \begin{macrocode}
393 \newif\if@hyper@back@pages@
394 \@hyper@back@pages@true
395 \DeclareOption{pages}{\@hyper@back@pages@true}
396 \DeclareOption{sections}{\@hyper@back@pages@false}
397 \ProcessOptions
398 %</backcite>
399 % \end{macrocode}
400 %
401 % \Finale