Debian Codegraph @

texmf-dist/source/latex/labelschanged/labelschanged.dtx

raw
1 % \iffalse meta-comment
2 %
3 % Packaged, documented, and maintained by Brian Dunn.
4 %
5 % Based on code by David Carlisle.
6 %
7 % In the public domain.
8 %
9 % \fi
10 %
11 % \iffalse
12 %<package>\NeedsTeXFormat{LaTeX2e}[1999/12/01]
13 %<package>\ProvidesPackage{labelschanged}
14 %<package> [2024/01/12 v1.01 Identifies endlessly-changing labels.]
15 %
16 %<*driver>
17 \documentclass{ltxdoc}
18
19 \usepackage{labelschanged}
20
21
22 \usepackage{xcolor}
23 \definecolor{myurlcolor}{rgb}{0,0,.7}
24 \definecolor{mylinkcolor}{rgb}{.7,0,0}
25
26 \usepackage[bookmarks=true,hidelinks,%
27 colorlinks,linkcolor=mylinkcolor,urlcolor=myurlcolor,%
28 pageanchor=true,hyperindex=true,
29 ]{hyperref}
30
31 \hypersetup{%
32 pdfinfo={%
33 Title={The Labelschanged Package},%
34 Author={Brian Dunn},%
35 Subject={LaTeX labels.},%
36 Keywords={LaTeX, labels, warning, changed}%
37 }}
38
39 \DeclareRobustCommand{\pkg}[1]{\textsf{#1}}
40
41 \setlength{\parindent}{0em}
42 \setlength{\parskip}{1.4ex}
43 \setcounter{secnumdepth}{0}
44
45 \setcounter{IndexColumns}{2}
46
47 \DisableCrossrefs
48 \CodelineIndex
49 \RecordChanges
50 \begin{document}
51 \DocInput{labelschanged.dtx}
52 \end{document}
53 %</driver>
54 % \fi
55 %
56 % \iffalse
57 %<*package>
58 % \fi
59 %
60 %
61 % \CheckSum{19}
62 %
63 % \CharacterTable
64 % {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
65 % 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
66 % Digits \0\1\2\3\4\5\6\7\8\9
67 % Exclamation \! Double quote \" Hash (number) \#
68 % Dollar \$ Percent \% Ampersand \&
69 % Acute accent \' Left paren \( Right paren \)
70 % Asterisk \* Plus \+ Comma \,
71 % Minus \- Point \. Solidus \/
72 % Colon \: Semicolon \; Less than \<
73 % Equals \= Greater than \> Question mark \?
74 % Commercial at \@ Left bracket \[ Backslash \\
75 % Right bracket \] Circumflex \^ Underscore \_
76 % Grave accent \` Left brace \{ Vertical bar \|
77 % Right brace \} Tilde \~}
78
79
80
81 % \changes{v1.0}{2017/12/11}{\ 2017/12/11: New pkg.}
82 % \changes{v1.01}{2024/01/12}{\ 2024/01/12}
83 % \changes{v1.01}{2024/01/12}{Updated contact info.}
84
85
86
87 % \GetFileInfo{labelschanged.sty}
88 %
89 % \DoNotIndex{\newcommand,\renewcommand,\addtocounter,\begin,\end,\begingroup,\endgroup}
90 % \DoNotIndex{\global,\ifbool,\ifthenelse,\isequivalentto,\let}
91 % \DoNotIndex{\booltrue,\boolfalse}
92 % \expandafter\DoNotIndex\expandafter{\detokenize{\(,\),\,,\\,\#,\$,\%,\^,\_,\~,\ ,\&,\{,\}}}
93 %
94 % \begin{center}
95 % \thispagestyle{empty}
96 % \vfill
97 % \vfill
98 % \Huge The \textbf{labelschanged} package \medskip
99 %
100 % \bigskip
101 %
102 % \large
103 % Identifies labels which cause endless ``may have changed'' warnings,
104 % and also labels which are ``multiply-defined''. \\
105 %
106 % \bigskip
107 %
108 % \normalsize \fileversion\ --- \filedate
109 %
110 % \footnotesize
111 % Packaged, documented, and maintained by \textsc{Brian Dunn}
112 %
113 % In the public domain.
114 %
115 % Github: \url{https://github.com/bdtc/labelschanged}
116 %
117 % \end{center}
118 %
119 %
120 % \thispagestyle{empty}
121 %
122 %
123 % \section{``Label(s) may have changed.''}
124 %
125 % Several conditions can cause \LaTeX\ labels to keep changing,
126 % no matter how many times a document is recompiled.
127 % \begin{description}
128 % \item[Dynamic references:] Some packages, such as \pkg{varioref},
129 % generate text references which dynamically change depending on the location
130 % of each float, and these changing messages may then cause the floats themselves to move.
131 %
132 % \item[Margin/foot notes:] References in margin or foot notes may have a similar effect.
133 %
134 % \item[Active characters:] Due to the way changing labels are detected,
135 % problems may also be caused by active characters in captions or section names.
136 % \end{description}
137 %
138 % In these circumstances, the warning
139 % \begin{quote}
140 % \small
141 % \texttt{LaTeX Warning: \\
142 % Label(s) may have changed. Rerun to get cross-references right.}
143 % \end{quote}
144 % reoccurs despite multiple document re-compiles.
145 % Locating the problem labels may be difficult, as there may not be any message
146 % identifying which labels have changed.
147 %
148 %
149 % \section{Locating the changing labels}
150 %
151 % In the preamble of the document, place:
152 % \begin{quote}
153 % \ttfamily
154 % \cs{usepackage}\{labelschanged\}
155 % \end{quote}
156 % The \pkg{labelschanged} package will print the names of the labels which changed,
157 % and their associated definitions before and after the recompile.
158 % \begin{quote}
159 % \ttfamily
160 % Label `xyz' has changed: \\
161 % \rmfamily\small
162 % \textless{}before/after comparisons\textgreater
163 % \end{quote}
164 %
165 %
166 % \section{Solutions}
167 %
168 % \begin{description}
169 % \item[Dynamic references:]
170 % \pkg{varioref} issues a warning if the reference text spans a page break.
171 % \cs{fullref} or a plain \cs{ref} may be used instead.
172 % \item[Margin notes:] See the packages \pkg{marginfit}, \pkg{mparhack}, \pkg{marginfix},
173 % and \pkg{marginnote} for possible improvements in margin note placement, which
174 % then may resolve the changing labels problem.
175 % \item[Footnotes:] See the packages \pkg{footnotehyper}, \pkg{footnote},
176 % and \pkg{ftnright} for possible improvements in footnote placement,
177 % which again may resolve the changing labels problem.
178 % For \pkg{footmisc}, try avoiding the |perpage| option.
179 % \item[Active characters:] The sectioning commands
180 % (\cs{chapter}, \cs{section}, etc.)
181 % and the \cs{caption} command all have an optional ``short'' argument
182 % which, if provided, is used in the table of contents and list of figures/tables
183 % instead of the regular argument.
184 % \begin{quote}
185 % |\section[Simple heading name]{Complicated heading name}| \\
186 % |\caption[Simple caption]{Complicated caption}|
187 % \end{quote}
188 % Providing a simplified caption or section heading may resolve the problem of
189 % incorrectly detecting changing labels.
190 %
191 % \item[\pkg{memoir} and \pkg{breqn}:] See \href
192 % {https://tex.stackexchange.com/questions/331209/warning-labels-may-have-changed-with-breqn}
193 % {https://tex.stackexchange.com/questions/331209/ \\
194 % \hspace*{2em}warning-labels-may-have-changed-with-breqn}
195 % \end{description}
196 %
197 %
198 % \section{Multiply-defined labels}
199 %
200 % A bonus side-effect of the \pkg{labelschanged} packages is that
201 % multiply-defined labels are also listed at the end of the compilation.
202 % While warnings of multiply-defined labels also appear earlier in the log,
203 % listing them again at the end makes it easier to quickly identify those
204 % which are a problem.
205 %
206 % Avoid using |\label{}| or |\bibitem{}|.
207 %
208 %
209 % \section{Missing references}
210 %
211 % Unfortunately, locating missing references still requires searching the log to
212 % find which are a problem.
213 %
214 %
215 % \clearpage
216 %
217 % \section{References}
218 %
219 % This code is taken almost verbatim from David Carlisle's reply to a post on
220 % \textsc{TeX-LaTeX Stack Exchange}:
221 % \begin{quote}
222 % \ttfamily
223 % \href
224 % {https://tex.stackexchange.com/questions/154594/how-to-diagnose-a-permanent-labels-may-have-changed-warning}
225 % {https://tex.stackexchange.com/questions/154594/ \\ \hspace*{2em} how-to-diagnose-a-permanent-labels-may-have-changed-warning}
226 % \end{quote}
227 %
228 % David has given permission to have this reply converted to a \LaTeX\ package,
229 % and has placed his \textsc{Stack Exchange} posts the in public domain, per:
230 % \begin{quote}
231 % \url{https://tex.meta.stackexchange.com/a/3332/1090}
232 % \end{quote}
233 %
234 % For other discussion on this topic, see:
235 % \begin{quote}
236 % \ttfamily
237 % \href
238 % {https://tex.stackexchange.com/questions/109178/why-does-the-compiler-keeps-telling-me-forever-to-rerun-because-labels-have-ch}
239 % {https://tex.stackexchange.com/questions/109178/ \\
240 % \hspace*{2em} why-does-the-compiler-keeps-telling-me-forever- \\
241 % \hspace*{2em} to-rerun-because-labels-have-ch}
242 % \end{quote}
243 %
244 %
245 % \StopEventually{
246 % \PrintChanges
247 % ^^A \PrintIndex
248 % }
249 %
250 % \clearpage
251 %
252 % \section{Code}
253 %
254 % At the end of the document, the |.aux| file is read back while \cs{newlabel}
255 % and \cs{bibcite} are effectively redefined as:
256 % \begin{quote}
257 % |\def\newlabel{\@testdef r}| \quad ---\,and\,--- \\
258 % |\def\bibcite{\@testdef b}|
259 % \end{quote}
260 %
261 % While the |.aux| file is read, each label's new definition as given in the
262 % |.aux| file is compared to its existing definition as defined by |r@<label>|
263 % or |b@<label>|.
264 %
265 % \begin{macro}{\@testdef} \marg{r -or- b} \marg{label} \marg{new definition}
266 % \begin{macrocode}
267 \def\@testdef #1#2#3{%
268 % \end{macrocode}
269 % Remember the new definition for comparison purposes:
270 % \begin{macrocode}
271 \def\reserved@a{#3}%
272 % \end{macrocode}
273 % Compare with the old definition. No action if the same.
274 % \begin{macrocode}
275 \expandafter \ifx \csname #1@#2\endcsname \reserved@a \else%
276 % \end{macrocode}
277 % If different, print a warning:
278 % \begin{macrocode}
279 \typeout{^^JLabel `#2' has changed:^^J%
280 % \end{macrocode}
281 % Display the new meaning:
282 % \begin{macrocode}
283 \meaning\reserved@a^^J%
284 % \end{macrocode}
285 % Display the old meaning:
286 % \begin{macrocode}
287 \expandafter\meaning\csname #1@#2\endcsname^^J}%
288 % \end{macrocode}
289 % Remember that labels have changed:
290 % \begin{macrocode}
291 \@tempswatrue%
292 \fi%
293 }
294 % \end{macrocode}
295 % \end{macro}
296
297 %
298 % \iffalse
299 %</package>
300 % \fi
301 %
302
303 %
304 % ^^A At end:
305 %
306 % ^^A \clearpage
307 % ^^A \pagestyle{plain}
308 % \phantomsection
309 % \addcontentsline{toc}{section}{Change History and \indexname}
310 %
311 % \pagestyle{plain}
312 %
313 % \Finale
314 \endinput
315
316
317 To create the change log:
318 makeindex -s gglo.ist -o labelschanged.gls labelschanged.glo
319 makeindex -s gind.ist labelschanged.idx