Debian Codegraph @

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

raw
1 %
2 % \iffalse meta-comment
3 %
4 % Copyright 2024–2025 Brian Dunn
5 %
6 % This work may be distributed and/or modified under the
7 % conditions of the LaTeX Project Public License, either version 1.3
8 % of this license or (at your option) any later version.
9 % The latest version of this license is in
10 % http://www.latex-project.org/lppl.txt
11 % and version 1.3 or later is part of all distributions of LaTeX
12 % version 2005/12/01 or later.
13 %
14 % \fi
15
16 %
17 % \iffalse
18 %<package>\NeedsTeXFormat{LaTeX2e}
19 %<package>\ProvidesPackage{verifycommand}
20 %<package> [2025/03/07 v1.11 Verify definitions have not changed.]
21 %
22 %<*driver>
23 \documentclass{ltxdoc}
24
25 \newcommand*{\mypackagename}{verifycommand}
26 \newcommand{\quicksummary}{Verifies that definitions have not changed.}
27
28
29 % \usepackage{lmodern}
30 \usepackage{erewhon}
31 \usepackage{roboto}
32 % \usepackage{sourcesanspro}
33 \usepackage{inconsolata}
34 % \usepackage{libertine}
35 \usepackage[T1]{fontenc}
36 \usepackage[utf8]{inputenc}
37 \usepackage{textcomp} % provides \degree, \textquotesingle, \textmu
38
39
40 \newcommand*{\TakeFourierOrnament}[1]{{%
41 \fontencoding{U}\fontfamily{futs}\selectfont\char#1}}
42
43 \newcommand*{\textwarning}{\TakeFourierOrnament{66}}
44
45 % copy/paste special unicode symbols:
46 \input{glyphtounicode}
47 \pdfglyphtounicode{prime}{2032}% hex
48 \pdfglyphtounicode{diameter}{2300}% diameter
49 \pdfglyphtounicode{warningsign}{26A0}% warning sign
50 \pdfgentounicode=1
51
52 \usepackage{newunicodechar}
53 \newunicodechar{ff}{ff}
54 \newunicodechar{fi}{fi}
55 \newunicodechar{fl}{fl}
56 \newunicodechar{ffi}{ffi}
57 \newunicodechar{ffl}{ffl}
58 % \newunicodechar{°}{\degree}
59 \newunicodechar{ρ}{\ensuremath{\rho}}
60 \newunicodechar{⨯}{\texttimes}
61 \newunicodechar{⁄}{\textfractionsolidus}
62 % \newunicodechar{®}{\textregistered}
63 % \newunicodechar{©}{\textcopyright}
64 \newunicodechar{—}{---}
65 \newunicodechar{–}{--}
66 % \newunicodechar{”}{''}
67 % \newunicodechar{“}{``}
68 % \newunicodechar{§}{\S}
69 % \newunicodechar{¶}{\P}
70 % \newunicodechar{†}{\dag}
71 \newunicodechar{‡}{\ddag}
72 \newunicodechar{⚠}{\textwarning}
73
74 \usepackage{etoolbox}
75
76 \usepackage{metalogox}
77
78 \usepackage{microtype}
79
80 \usepackage{nowidow}
81
82
83 \usepackage[svgnames]{xcolor}
84 \definecolor{myurlcolor}{rgb}{0,0,.7}
85 \definecolor{mylinkcolor}{rgb}{.7,0,0}
86 \definecolor{codecolor}{rgb}{0,.4,.2}
87 \definecolor{overviewcolor}{rgb}{0,.2,.4}
88
89
90 %\usepackage{graphicx}
91 %\graphicspath{{images/}}
92
93 %\usepackage{enumitem}
94
95 \usepackage{needspace}
96
97 %\usepackage{array}
98 %\usepackage{booktabs}
99 %\usepackage{threeparttable}
100
101 %\usepackage{fancybox}% must be loaded before fancyvrb
102 %\usepackage{fancyvrb}
103
104
105 %\usepackage{caption}
106 %\usepackage{newfloat}
107
108 %\captionsetup{labelfont={small,bf},textfont={small,bf}}
109
110 %\captionsetup*[figure]{
111 % style=default, justification=centering,
112 % margin=0pt, parskip=0pt, skip=2ex,
113 % labelfont={small,bf},textfont={small,bf}
114 %}
115
116 %\captionsetup*[table]{
117 % style=default, justification=centering,
118 % margin=0pt, parskip=0pt, skip=1ex,
119 % labelfont={small,bf},textfont={small,bf},
120 % position=top
121 %}
122
123 %\captionsetup*[subfigure]{
124 % style=default, justification=centering,
125 % margin=0pt, parskip=0pt, skip=2ex,
126 % labelfont={small},textfont={small}
127 %}
128
129 %\captionsetup*[subtable]{
130 % style=default, justification=centering,
131 % margin=0pt, parskip=0pt, skip=1ex,
132 % labelfont={small},textfont={small},
133 % position=top
134 %}
135
136 %\captionsetup*[wrapfigure]{
137 % style=default, justification=centering,
138 % margin=0pt, parskip=0pt, skip=2ex,
139 % labelfont={small,bf},textfont={small,bf}
140 %}
141
142 %\captionsetup*[wraptable]{
143 % style=default, justification=centering,
144 % margin=0pt, parskip=0pt, skip=1ex,
145 % labelfont={small,bf},textfont={small,bf}
146 %}
147
148
149
150 %\usepackage{blindtext}
151
152
153
154 %\usepackage{tikz}
155 %\usetikzlibrary{positioning,fit,backgrounds,calc,shapes.geometric,shadows}
156
157 %\usepackage[framemethod=tikz]{mdframed}
158
159 %\mdfdefinestyle{boxroundshadow}{linewidth=1pt,innerleftmargin=0in,innerrightmargin=0in,%
160 %innertopmargin=0in,innerbottommargin=0in,%
161 %align=center,roundcorner=3pt,shadow=true,shadowcolor=black!50,shadowsize=4pt,%
162 %leftmargin=0pt,rightmargin=0pt,%
163 %frametitlebackgroundcolor=black!15,%
164 %skipabove=0ex,skipbelow=0ex,%
165 %frametitlerulewidth=1pt,frametitleaboveskip=5pt,%
166 %}
167
168 %\newmdenv[style=boxroundshadow,align=center]{mdtightframe}
169
170 %\newmdenv[style=boxroundshadow,align=center,%
171 % innertopmargin=3pt,innerbottommargin=3pt,%
172 % innerleftmargin=3pt,innerrightmargin=3pt]{mdlooseframe}
173
174
175 \usepackage[normalem]{ulem}
176
177
178 %\usepackage{tocdata}[2019/03/21]% v2.02 or later
179
180 \usepackage{tocloft}
181 \setlength{\cftsubsecnumwidth}{3em}
182 \setlength{\cftsubsubsecindent}{2.8em}
183 \setlength{\cftsubsubsecnumwidth}{4em}
184 \setlength{\cftbeforesubsecskip}{1ex}
185
186 % \usepackage{titletoc}
187
188
189
190 \usepackage{titleps}
191
192 \newpagestyle{pageheadfoot}{
193 \headrule
194 \sethead{\pkg{\mypackagename}}{}{\thepage}
195 % \renewcommand{\makefootrule}{\rule[2.5ex]{\linewidth}{.4pt}}
196 \setfoot{}{}{}
197 }
198
199 \pagestyle{pageheadfoot}
200
201
202 % Indexing, logos, \Describexxxx, etc:
203 \usepackage{dtxdescribe}[2023/01/03]
204
205
206
207 \usepackage{splitidx}
208
209 \newindex[Index of Objects]{idx}
210 %\newindex[General Index]{gen}
211 % \newindex[Troubleshooting Index]{trb}
212 %\newindex[Index of Indexes]{meta}
213
214 \makeindex
215
216 \newcommand*{\gindex}[1]{\sindex[gen]{#1}\ignorespaces}
217
218 % \trouble[watchout phrase]{index entry}
219 \newcommand*{\trouble}[2][]{%
220 \ifblank{#1}{}{%
221 \watchout[#1]%
222 }%
223 % \sindex[trb]{#2}%
224 \gindex{#2}%
225 \ignorespaces%
226 }
227
228
229 \newcommand*{\MDfive}{\begingroup\textup{\acro{MD5}}\endgroup}
230
231 %\setlength{\floatsep}{5ex plus 1ex minus 1ex}
232 %\setlength{\dblfloatsep}{5ex plus 1ex minus 1ex}
233
234
235 \usepackage{\mypackagename}
236 %\usepackage[disable]{\mypackagename}
237
238
239
240
241 \AtBeginDocument{
242 \hypersetup{%
243 pdfinfo={%
244 Title={The LaTeX \mypackagename\ package},%
245 Author={Brian Dunn},%
246 Subject={Verify LaTeX definitions are unchanged.},%
247 Keywords={LaTeX}%
248 colorlinks,%
249 linkcolor=mylinkcolor,%
250 urlcolor=myurlcolor,%
251 pageanchor=true,
252 }}
253
254 \pdfstringdefDisableCommands{
255 \def\quad{ }
256 \def\\{ }
257 \def\pkg#1{#1}
258 \def\cs#1{\textbackslash#1}
259 \def\env#1{#1}
260 \def\,{ }
261 \def\prog#1{#1}
262 \def\LuaLaTeX{LuaLaTeX}
263 \def\XeLaTeX{XeLaTeX}
264 \def\TeX{TeX}
265 \def\LaTeX{LaTeX}
266 \def\Dash{ --- }
267 \def\dash{ -- }
268 \def\element#1{#1}
269 \def\attribute#1{#1}
270 \def\MDfive{MD5}
271 }
272 }% AtBeginDocument
273
274 \AddToHook{begindocument/before}{% Before .aux file is loaded.
275 \usepackage{cleveref}% If needed.
276 }
277
278
279
280
281 \setlength{\marginparsep}{1em}
282 \setlength{\marginparpush}{.7ex}
283 \setlength{\IndexMin}{40ex}
284
285 \setcounter{IndexColumns}{2}
286
287
288 \DisableCrossrefs
289 \CodelineIndex
290 \RecordChanges
291 \begin{document}
292 \DocInput{\mypackagename.dtx}
293 \end{document}
294 %
295 %</driver>
296 %
297 % \fi
298 %
299 % \iffalse
300 %<*package>
301 % \fi
302 %
303
304 % \changes{v1.00}{2024/01/11}{\ 2024/01/11 Initial version.}
305 % \changes{v1.10}{2024/09/03}{\ 2024/09/03}
306 % \changes{v1.11}{2025/03/07}{\ 2025/03/07}
307 % \changes{v1.11}{2025/03/07}{Documentation improvements.}
308
309
310 % \GetFileInfo{\mypackagename.sty}
311 %
312 % \DoNotIndex{\newcommand,\renewcommand,\addtocounter,\begin,\end,\begingroup,\endgroup}
313 % \DoNotIndex{\global,\ifbool,\ifthenelse,\isequivalentto,\let}
314 % \DoNotIndex{\booltrue,\boolfalse}
315 % \expandafter\DoNotIndex\expandafter{\detokenize{\(,\),\,,\\,\#,\$,\%,\^,\_,\~,\ ,\&,\{,\}}}
316 %
317 %
318 % \thispagestyle{empty}
319 % \begin{center}
320 % \vfill
321 % ^^A \includegraphics[width=.3\linewidth]{\mypackagename_logo.pdf}
322 % \vfill
323 % {\Huge The \LaTeX\\
324 % \pkg{\mypackagename}\\
325 % Package}
326 % \bigskip
327 %
328 % \fileversion{} --- \filedate
329 %
330 % \bigskip
331 %
332 % {\small\textcopyright{} 2024--2025} Brian Dunn\\ \small \url{https://github.com/bdtc/verifycommand}
333 %
334 % \vspace{.5in}
335 %
336 % {\Large \textup{\quicksummary}}
337 %
338 %
339 % \vfill
340 %
341 %
342 % \vfill
343 %
344 %
345 % \begin{abstract}
346 % \noindent
347 % For package authors who patch code from other packages.
348 %
349 % To improve reliability,
350 % the \pkg{verifycommand} package provides a way to verify that
351 % macros or environments have not changed since the patches were
352 % last designed.
353 % This may be checked before applying the patch.
354 % If a definition is not as expected, a warning is issued.
355 % At the end of the compile, a list of all changed definitions is displayed.
356 %
357 % Conditionals are provided, allowing multiple versions of a definition
358 % to be tested and patched, warning if no known version is found.
359 % Conditionals also allow the package to verify that several macros
360 % are unchanged before taking a single common action.
361 %
362 % \vfill
363 %
364 % \footnotesize
365 % \begin{description}
366 % \item[License:] \
367 %
368 % This work may be distributed and/or modified under the
369 % conditions of the LaTeX Project Public License, either version 1.3
370 % of this license or (at your option) any later version.
371 % The latest version of this license is in
372 % http://www.latex-project.org/lppl.txt
373 % and version 1.3 or later is part of all distributions of LaTeX
374 % version 2005/12/01 or later.
375 % \end{description}
376 %
377 % \end{abstract}
378 %
379 % \vspace*{\fill}
380 % \vspace*{\fill}
381 % \vspace*{\fill}
382 % \end{center}
383 % \clearpage
384 %
385 % \tableofcontents
386 % ^^A \listofdtxexamplefloats
387 % ^^A \listoffigures
388 % ^^A \listoftables
389 %
390 %
391 % \thispagestyle{pageheadfoot}
392 %
393 % \clearpage
394 %
395 %^^A \part{verifycommand.sty}
396 %
397 % \section{Introduction}
398 %
399 % Patching a macro or environment from another package risks
400 % the possibility that the other author has made an update
401 % and changed something unexpected,
402 % breaking your own package when it tries to apply the patch.
403 %
404 % The traditional way to check a definition you wish to modify
405 % is to copy the expected definition into your package under a new name,
406 % then compare to see if the current definition
407 % is the same as it was when your package was first created.
408 % For a few definitions this may work well, but as the number
409 % of patches goes up things get more and more unwieldy.
410 %
411 % The \pkg{verifycommand} package uses \MDfive\ checksums instead of
412 % copying entire definitions.
413 % If something has changed, a warning is issued telling the
414 % name of the defintion, and optionally telling the name of your
415 % own package and the package being modified.
416 % This improves code reliability, and allows package authors
417 % to get an early warning when an author of some other package
418 % has made an unexpected change.
419 %
420 % In many cases, the patch or replacement may still function correctly
421 % even when the original has changed in some way.
422 % For this reason, only a warning is issued, not an error.
423 %
424 %
425 % \section{How it works}
426 %
427 % \cs{VerifyCommand} and \cs{VerifyEnvironment} are used to test
428 % whether a definition has changed.
429 % Each definition is given an \MDfive\ checksum, which is compared to
430 % the expected checksum given as arguments of \cs{VerifyCommand}
431 % and \cs{VerifyEnvironment}.
432 % If a checksum does not match, a warning is issued,
433 % flagging the definition for attention.
434 %
435 % The \MDfive\ checksum is of the text of the code part of the underlying definition,
436 % as it would be displayed by the \cs{meaning} command.
437 % For environments, the end code is checked separately.
438 % The check detects changes in the replacement text of the definition,
439 % and may or may not detect changes in the number or type of parameters,
440 % \cs{long}, or type of robustness, depending on the type of definition.
441 % Some definitions may have the same checksum if they have the same
442 % replacement code but different argument types, for example
443 % a \cs{NewDocumentCommand} with two mandatory arguments vs another with one optional
444 % and one mandatory, if they both have the same replacement code.
445 %
446 % When something does not match, the current checksum is printed to
447 % the terminal, and the author may copy/paste that into the parameter of
448 % \cs{VerifyCommand} or \cs{VerifyEnvironment} to update the
449 % expected values.
450 %
451 %
452 % \section{Warnings}
453 %
454 % \changes{v1.10}{2024/09/03}{Docs: Added Warnings section.}
455 %
456 % The document \textit{\LaTeX\ for authors} (\cmds{texdoc usrguide}
457 % recommends the use of \LaTeX\ hooks where possible (\cmds{texdoc lthooks}).
458 %
459 % Commands created with \cs{NewDocumentCommand} and related may
460 % \watchout[kernel changes]
461 % change their definitions when the inner workings of
462 % \cs{NewDocumentCommand} are optimized.
463 % When this occurs, any checksums for these commands will
464 % change, even though the associated patches probably will continue to work.
465 % If you use \pkg{verifycommand} for these commands, expect the
466 % checksums to need updates at some point in the future.
467 %
468 % Use \cs{NewCommandCopy} and \cs{NewEnvironmentCopy} to copy commands
469 % for reuse. These work with all kinds of commmand definitions.
470 % See \cmds{texdoc usrguide} for details.
471 %
472 % Use \cs{ShowCommand} or \cs{ShowEnvironment} to see an existing definition,
473 % which again works with all forms of commands.
474 %
475 %
476 % \section{How to use \pkg{verifycommand}}
477 %
478 %
479 % \subsection{The user interface}
480 %
481 % \changes{v1.10}{2024/06/25}{Docs: Added conditional tests.}
482 %
483 % In the following, \oarg{yourpackagename} is the package doing the
484 % testing and patching,
485 % and \oarg{theirpackagename} is the package which defines
486 % the original macro.
487 % Using these optional package names make it easier to find where
488 % to make changes if needed.
489 %
490 % If there is only one optional argument,
491 % \watchout[optional arguments]
492 % it is used as \oarg{yourpackagename},
493 % to identify where to find the \cs{VerifyCommand} checksum entry.
494 % The second optional argument identifies what is being patched,
495 % in case it has been changed.
496 %
497 % \needspace{2\baselineskip}
498 % \DescribeMacro{\VerifyCommand} \oarg{yourpackagename} \oarg{theirpackagename}
499 % \marg{\cs{macroname}} \marg{\MDfive\ checksum}
500 %
501 % \needspace{3\baselineskip}
502 % \DescribeMacro{\VerifyEnvironment} \oarg{yourpackagename} \oarg{theirpackagename}
503 % \marg{\env{envname}} \\
504 % \fqquad \marg{begin \MDfive\ checksum} \marg{end \MDfive\ checksum}
505 %
506 % Use one of these macros just before patching a macro or environment,
507 % as seen below. A test is performed to see if the definition
508 % is as expected before applying a patch.
509 %
510 % Note that there is one checksum for \cs{VerifyCommand}, but there
511 % are two checksums for an environment: once for the begin section
512 % and one for the end section.
513 %
514 % It may be necessary to test for each of several possible versions of
515 % a definition, then patch accordingly. The following test and apply a
516 % true or false clause, without issuing a warning.
517 %
518 % \needspace{2\baselineskip}
519 % \DescribeMacro{\IfVerifyCommand} \oarg{yourpackagename} \oarg{theirpackagename}
520 % \marg{\cs{macroname}} \\
521 % \fqquad \marg{\MDfive\ checksum} \\
522 % \fqquad \marg{true} \marg{false}
523 %
524 % \needspace{3\baselineskip}
525 % \DescribeMacro{\IfVerifyEnvironmentBegin} \oarg{yourpackagename} \oarg{theirpackagename}
526 % \marg{\env{envname}} \\
527 % \fqquad \marg{begin \MDfive\ checksum} \\
528 % \fqquad \marg{true} \marg{false}
529 %
530 % \needspace{3\baselineskip}
531 % \DescribeMacro{\IfVerifyEnvironmentEnd} \oarg{yourpackagename} \oarg{theirpackagename}
532 % \marg{\env{envname}} \\
533 % \fqquad \marg{end \MDfive\ checksum} \\
534 % \fqquad \marg{true} \marg{false}
535 %
536 % Tests may be done as a group, either to try several versions of the same
537 % definition, or to verify several definitions and act if any of them fail:
538 %
539 % \DescribeMacro{\TestVerifyCommands} Starts a group of tests.
540 %
541 % \DescribeMacro{\IfVerifyCommandPassed} \marg{true} \marg{false}
542 % \quad Act if any of a group passed.
543 % May be used to try to patch multiple versions of a command.
544 %
545 % \DescribeMacro{\IfVerifyCommandFailed} \marg{true} \marg{false}
546 % \quad Act if any of a group failed.
547 % May be used to verify several definitions are unchanged.
548 %
549 % A warning may be also issued:
550 %
551 % \DescribeMacro{\VERCMDWarning} \marg{yourpackage} \marg{theirpackage} \marg{defn name}
552 % \quad Used to issue a warning that the macro has changed.
553 %
554 % See \cref{sec:conditionals} for examples of conditional tests.
555 %
556 %
557 % \subsection{Placing the macros}
558 %
559 % When first using \pkg{verifycommand}, use empty checksums, placing
560 % \cs{VerifyCommand} or \cs{VerifyEnvironment} before each place
561 % where something gets patched.
562 % This is probably not required where things are entirely replaced,
563 % or prepended or appended.
564 %
565 % \begin{sourceverb}
566 % \VerifyCommand{\LaTeX}{}
567 % (patch \LaTeX here)
568 %
569 % \VerifyCommand[mypackage]{\textcolor}{}
570 % (patch \textcolor here)
571 %
572 % \VerifyCommand[mypackage][graphics]{\rotatebox}{}
573 % (patch \rotatebox here)
574 %
575 % \VerifyEnvironment{tabbing}{}{}
576 % (patch tabbing here)
577 % \end{sourceverb}
578 %
579 %
580 % \subsection{Finding the checksums of the current definitions}
581 % \changes{v1.10}{2024/06/25}{Docs: ``Finding checksums'' reorganized.}
582 %
583 % The warnings are issued and the correct checksums are given.
584 % The type of warning depends on the usage:
585 % \begin{itemize}
586 % \item Verifying \cs{LaTeX} would print a warning showing
587 % the correct \MDfive\ checksum.
588 % \begin{sourceverb}
589 % Warning: A definition has changed:
590 % \LaTeX
591 % (FAAAC6146C9A80F46A1F029B67923851)
592 % on input line 464.
593 % \end{sourceverb}
594 % \item Verifying \cs{textcolor} would do the same,
595 % but as a \cs{PackageWarning} from \pkg{mypackage},
596 % which is the package doing the testing.
597 % \begin{sourceverb}
598 % Package mypackage Warning: A definition has changed:
599 % (mypackage) \textcolor
600 % (mypackage) (E1E2B5A908AA1BCDDF6BEA038596A381)
601 % (mypackage) on input line 465.
602 % \end{sourceverb}
603 % \item Verifying \cs{rotatebox} would also issue a warning from \pkg{mypackage},
604 % but also mention the package being tested, \pkg{graphics}.
605 % \begin{sourceverb}
606 % Package mypackage Warning: A definition has changed:
607 % (mypackage) graphics: \rotatebox
608 % (mypackage) (2472999B02C97AC847128AF24C55D150)
609 % (mypackage) on input line 466.
610 % \end{sourceverb}
611 % \item Verifying \env{tabbing} issues a separate warning
612 % for the begin and end sections.
613 % \begin{sourceverb}
614 % Warning: A definition has changed:
615 % tabbing
616 % (1AD73B4527AD30969CF3219F2FB1306B)
617 % on input line 518.
618 %
619 % Warning: A definition has changed:
620 % (end)tabbing
621 % (E8326AC43EE0A6E922A20F2A798BD177)
622 % on input line 518.
623 % \end{sourceverb}
624 % \end{itemize}
625 %
626 %
627 % At the end of the compile, a summary is given:
628 %
629 % \begin{sourceverb}
630 % --------------------------------
631 % Package verifycommand Warning: Definitions have changed.
632 % Patches for the following macros may need to be updated.
633 % See the previous warnings for line numbers.
634 %
635 % Syntax: Patching pkg -> Defining pkg: Macro (checksum)
636 % -----
637 % (verifycommand) \LaTeX
638 % (FAAAC6146C9A80F46A1F029B67923851)
639 % (verifycommand) mypackage -> \textcolor
640 % (E1E2B5A908AA1BCDDF6BEA038596A381)
641 % (verifycommand) mypackage -> graphics: \rotatebox
642 % (2472999B02C97AC847128AF24C55D150)
643 % (verifycommand) tabbing
644 % (1AD73B4527AD30969CF3219F2FB1306B)
645 % (verifycommand) (end)tabbing
646 % (E8326AC43EE0A6E922A20F2A798BD177)
647 % --------------------------------
648 % \end{sourceverb}
649 %
650 %
651 % \subsection{Assigning the checksums}
652 % Copy the checksums from the warnings messages into the source.
653 % When this is done, there are no more \pkg{verifycommand} warnings
654 % unless one of these defintions changes:
655 %
656 % \begin{sourceverb}
657 % \VerifyCommand{\LaTeX}{FAAAC6146C9A80F46A1F029B67923851}
658 % (patch \LaTeX here)
659 %
660 % \VerifyCommand[mypackage]{\textcolor}
661 % {E1E2B5A908AA1BCDDF6BEA038596A381}
662 % (patch \textcolor here)
663 %
664 % \VerifyCommand[mypackage][graphics]{\rotatebox}
665 % {2472999B02C97AC847128AF24C55D150}
666 % (patch \rotatebox here)
667 %
668 % \VerifyEnvironment{tabbing}
669 % {1AD73B4527AD30969CF3219F2FB1306B}% beginning code
670 % {E8326AC43EE0A6E922A20F2A798BD177}% endind code
671 % (patch tabbing here)
672 % \end{sourceverb}
673 %
674 %
675 % \subsection{When a definition has changed}
676 %
677 % When something being verified changes at a later time, the resulting
678 % warning will let the user know that the patches may not work
679 % as expected.
680 % Because the test is done before the patch,
681 % this warning will be issued before the patch is even attempted.
682 %
683 % When testing many packages in bulk, a utility such as \cmds{grep}
684 % can report which macros have changed.
685 % Search the log file for ``\texttt{(verifycommand)}''.
686 %
687 %
688 % \subsection{Testing for changed macros}
689 % \label{sec:conditionals}
690 %
691 % \changes{v1.10}{2024/06/25}{Docs: Added conditional tests.}
692 %
693 % To test to see if a macro or environment has changed, use
694 % \cs{IfVerifyCommand}, \cs{IfVerifyEnvironmentBegin},
695 % or \cs{IfVerifyEnvironmentEnd}.
696 %
697 % Example:
698 % \begin{sourceverb}
699 % \IfVerifyCommand[mypackage][LaTeX kernel]{\LaTeX}{123}{True}{False}
700 % \end{sourceverb}
701 % Result: \IfVerifyCommand[mypackage][LaTeX kernel]{\LaTeX}{}{True}{False}
702 %
703 % Example:
704 % \begin{sourceverb}
705 % \IfVerifyCommand[mypackage][LaTeX kernel]{\LaTeX}
706 % {FAAAC6146C9A80F46A1F029B67923851}
707 % {True}{False}
708 % \end{sourceverb}
709 % Result:
710 % \IfVerifyCommand[mypackage][LaTeX kernel]{\LaTeX}
711 % {FAAAC6146C9A80F46A1F029B67923851}
712 % {True}{False}
713 % (Assuming \cs{LaTeX} has not actually changed since
714 % this manual was generated.)
715 %
716 % Example:
717 % \begin{sourceverb}
718 % \IfVerifyEnvironmentEnd[mypackage][LaTeX kernel]{tabbing}
719 % {E8326AC43EE0A6E922A20F2A798BD177}
720 % {True}{False}
721 % \end{sourceverb}
722 % Result:
723 % \IfVerifyEnvironmentEnd[mypackage][LaTeX kernel]{tabbing}
724 % {E8326AC43EE0A6E922A20F2A798BD177}
725 % {True}{False}
726 %
727 % If the \pkg{verifycommand} package is disabled, these tests
728 % will always return true.
729 %
730 % These tests do not issue warnings if the test fails, so they may
731 % be used to test against several possible definitions, chosing the
732 % appropriate patch depending on which match is found.
733 %
734 % To try to patch multiple versions of the same command,
735 % and issue a warning if no match is found:
736 %
737 % \begin{sourceverb}
738 % \TestVerifyCommands
739 %
740 % \IfVerifyCommand[mypackage][theirpackage]{\theirmacro}
741 % {12312312312312312321312312312312}
742 % {(Patch an older version of the macro.)}% true
743 % {}% false
744 %
745 % \IfVerifyCommand[mypackage][theirpackage]{\theirmacro}
746 % {45645645645645645645645645645645}
747 % {(Patch a newer version of the macro.)}% true
748 % {}% false
749 %
750 % \IfVerifyCommandPassed
751 % {}% true: One of the patches worked.
752 % {\VERCMDWarning{mypackage}{theirpackage}{\theirmacro}}% false
753 % \end{sourceverb}
754 %
755 % To verify several commands have not changed:
756 %
757 % \begin{sourceverb}
758 % \TestVerifyCommands
759 %
760 % \VerifyCommand[mypackage][theirpackage]{\firstmacro}
761 % {78978978978978978978978978978978}
762 % \VerifyCommand[mypackage][theirpackage]{\secondmacro}
763 % {27272727272727272727277272727272}
764 % \VerifyCommand[mypackage][theirpackage]{\thirdmacro}
765 % {84838483848384838483848384838483}
766 %
767 % \IfVerifyCommandFailed
768 % {Something is not correct. (Warnings have been issued above.)}
769 % {}% All are fine.
770 % \end{sourceverb}
771 %
772 %
773 % \subsection{Disabling the package}
774 %
775 % \pkg{verifycommand} relies on knowing the internal structure of
776 % various kinds of definitions. It is possible that these may change,
777 % causing endless warnings for that kind of definition.
778 % Should that happen, it will be necessary to disable the \pkg{verifycommand}
779 % package until it can be updated.
780 % Use the \optn{disable} option to do so.
781 %
782 % \begin{sourceverb}
783 % \usepackage[disable]{verifycommand}
784 % \end{sourceverb}
785 %
786 % Package warnings will stop,
787 % and the conditional tests will always return true.
788 %
789 % If the package is disabled, the boolean \bool{VERCMDenable}
790 % will be |false|. This may be used to help decide which patches
791 % to apply as a default.
792 %
793 %
794 % ^^A To trigger the checksums to be copied into the exmaples:
795 % \typeout{(verifycommand): The following warnings that definitions have changed}
796 % \typeout{are expected, and are for demonstration purposes:}
797 % \VerifyCommand{\LaTeX}{}
798 % \VerifyCommand[mypackage]{\textcolor}{}
799 % \VerifyCommand[mypackage][graphics]{\rotatebox}{}
800 % \VerifyEnvironment{tabbing}{}{}
801 %
802 % \clearpage
803 %
804 % ^^A \StopEventually{\PrintChanges\PrintIndex}
805 %
806 % \makeatletter
807 %
808 % \StopEventually{
809 % ^^A \part{Change History and Index}
810 % ^^A \part{Change History}
811 %
812 %
813 % \pagestyle{plain}
814 %
815 % ^^A Each index has a prologue which creates its own \part, label,
816 % ^^A and meta index entry.
817 % \GlossaryPrologue{
818 % \part{Change History}
819 % ^^A \section{Chg Hist}
820 % \label{sec:changehistory}
821 % ^^A \sindex[meta]{Change History}
822 % \markboth{{Change History}}{{Change History}}
823 %
824 % ^^A For the most recent changes, see page \pageref{sec:changesend}.
825 %
826 % }
827 % \PrintChanges
828 % \phantomsection
829 % \label{sec:changesend}
830 % \clearpage
831 %
832 % ^^A The instructions for the Index of Objects:
833 % \IndexPrologue{
834 % \clearpage
835 % \expandafter\part\expandafter{\indexname}
836 % \label{sec:index\indexshortcut}
837 % ^^A \sindex[meta]{\indexname}
838 % \markboth{Index of Objects}{Index of Objects}%
839 %
840 % This is an index of macros, environments, booleans, counters, lengths,
841 % packages, classes, options, keys, files, and various other programming objects.
842 % Each is listed by itself, and also by category.
843 % In some cases, they are further subdivided by [class].
844 %
845 % Numbers written in italic refer to the page
846 % where the corresponding entry is described;
847 % numbers underlined refer to the
848 % \ifcodeline@index
849 % code line of the
850 % \fi
851 % definition.
852 % ^^A ; numbers in roman refer to the
853 % ^^A \ifcodeline@index
854 % ^^A code lines
855 % ^^A \else
856 % ^^A pages
857 % ^^A \fi
858 % ^^A where the entry is used.
859 % }
860 %
861 % \printindex[idx][Index of Objects]
862 %
863 %
864 % ^^A The instructions for the General Index:
865 % \IndexPrologue{
866 % \clearpage
867 % \expandafter\part\expandafter{\indexname}
868 % \label{sec:index\indexshortcut}
869 % ^^A \sindex[meta]{\indexname}
870 %
871 % ^^A This is an index of instructions and concepts.
872 % ^^A Look here when wondering how to do something, and
873 % ^^A check the Troubleshooting Index when something goes wrong.
874 % This is a general index, including how-to and troubleshooting.
875 % }
876 %
877 % \printindex[gen][General Index]
878 %
879 %
880 % ^^A% The instructions for the Troubleshooting Index:
881 % ^^A% \IndexPrologue{
882 % ^^A% \clearpage
883 % ^^A% \expandafter\part\expandafter{\indexname}
884 % ^^A% \label{sec:index\indexshortcut}
885 % ^^A% \sindex[meta]{\indexname}
886 % ^^A%
887 % ^^A% This index is a sorted reference of problems and solutions.
888 % ^^A% In order to make it easier to locate a solution,
889 % ^^A% the same issue may be addressed by more than one entry.
890 % ^^A%
891 % ^^A% Entries with higher page numbers are often duplicates of entries with
892 % ^^A% lower page numbers, as the same warning may occur within the user manual
893 % ^^A% and again within the source code for a given package.
894 % ^^A% }
895 % ^^A%
896 % ^^A% \printindex[trb][Troubleshooting Index]
897 %
898 %
899 % ^^A The meta index does not get a meta index entry pointing to itself:
900 % \IndexPrologue{
901
902 % \clearpage
903 % \expandafter\part\expandafter{\indexname}
904 % \label{sec:index\indexshortcut}
905 % }
906 %
907 % ^^A \printindex[meta][Index of Indexes]
908 %
909 % \typeout{--------------------------------}
910 % \typeout{The following warning that}
911 % \typeout{definitions have changed is an}
912 % \typeout{example of the output of this}
913 % \typeout{package, and is not evidence of}
914 % \typeout{a problem with the verifycommand}
915 % \typeout{manual or documentation.}
916 % \typeout{--------------------------------}
917 %
918 % }
919 %
920 % \makeatother
921 %
922 %
923 %
924 %
925 % \section{Code}
926 % ^^A *source
927 %
928 % \subsection{Package requirements}
929 % \begin{macrocode}
930 \RequirePackage{etoolbox}
931 \RequirePackage{iftex}
932 % \end{macrocode}
933 %
934 %
935 % \subsection{Package options}
936 %
937 % Package option to disable all functions.
938 %
939 % \DescribeBoolean{VERCMDenable} Is the package enabled?
940 % \begin{macrocode}
941 \newbool{VERCMDenable}
942 \booltrue{VERCMDenable}
943 % \end{macrocode}
944 %
945 % \DescribeOption{disable} Turn off all functions.
946 % \begin{macrocode}
947 \DeclareOption{disable}{%
948 \boolfalse{VERCMDenable}%
949 \typeout{----}%
950 \typeout{Package verifycommand: Turned off by option 'disable'.}%
951 \typeout{----}%
952 }
953
954 \ProcessOptions\relax
955 % \end{macrocode}
956 %
957 %
958 % \subsection{Support macros}
959 %
960 % \begin{macro}{\VERCMD@backslash} The literal |\| character.
961 %
962 % This is used later because some internal definitions use double |\\| as
963 % part of their name.
964 % \begin{macrocode}
965 \catcode`\&=0
966 &catcode`&\=12
967 &def&VERCMD@backslash{\}
968 &catcode`&\=0
969 \catcode`\&=4
970 % \end{macrocode}
971 % \end{macro}
972 %
973 %
974 %
975 %
976 % \subsection{\MDfive\ hashing}
977 %
978 % The \MDfive\ hash is used for \env{lateximage} filenames for \SVG\ math.
979 %
980 % The default definition if no MD5 function is found.
981 % This will be changed below if an MD5 function is available.
982 % \begin{macrocode}
983 \newcommand{\VERCMD@mdfivesum}[1]{%
984 \PackageError{verifycommand}
985 {No MD5 macro was found}
986 {%
987 Verifycommand must find the macros \protect\pdfmdfivesum\space
988 or \protect\mdfivesum.%
989 }
990 }
991 % \end{macrocode}
992 %
993 % The default for \pdfLaTeX, \dviLaTeX, up\LaTeX, etc:
994 % \begin{macrocode}
995 \ifdef{\pdfmdfivesum}
996 {\let\VERCMD@mdfivesum\pdfmdfivesum}
997 {}
998 % \end{macrocode}
999 %
1000 % For \LuaLaTeX:
1001 % \begin{macrocode}
1002 \ifLuaTeX
1003 \RequirePackage{pdftexcmds}
1004 \let\VERCMD@mdfivesum\pdf@mdfivesum
1005 \fi
1006 % \end{macrocode}
1007 %
1008 % For \XeLaTeX:
1009 % \begin{macrocode}
1010 \ifXeTeX
1011 \@ifundefined{pdffivesum}{}
1012 {\let\VERCMD@mdfivesum\pdfmdfivesum}
1013 \@ifundefined{mdfivesum}{}
1014 {\let\VERCMD@mdfivesum\mdfivesum}
1015 \fi
1016 % \end{macrocode}
1017
1018 % \begin{macro}{\VERCMD@mdfive} \marg{\cs{macroname}} \qquad
1019 % Compute \MDfive\ checksum, store in \cs{VERCMD@temp}.
1020 % \begin{macrocode}
1021 \def\VERCMD@mdfive#1{%
1022 \edef\VERCMD@temp{\VERCMD@mdfivesum{\meaning#1}}%
1023 }
1024 % \end{macrocode}
1025 % \end{macro}
1026 %
1027 %
1028 % \subsection{Issuing warnings}
1029 %
1030 % ^^A % \begin{macrocode}
1031 % ^^A \gdef\VERCMD@ProgError#1#2{%
1032 % ^^A \GenericError{%
1033 % ^^A (\jobname)\@spaces\@spaces\@spaces\@spaces
1034 % ^^A }{%
1035 % ^^A \jobname\ Error: #1%
1036 % ^^A }{%
1037 % ^^A Something has changed and the result may fail.%
1038 % ^^A }{#2}%
1039 % ^^A }
1040 % ^^A % \end{macrocode}
1041 %
1042 %
1043 % \begin{macro}{\VERCMD@whatchanged} Accumulates a list of changed definitions.
1044 % \begin{macrocode}
1045 \newcommand*{\VERCMD@whatchanged}{}
1046 % \end{macrocode}
1047 % \end{macro}
1048
1049 % \DescribeBoolean{VERCMD@this@ltxcmd} True if this command is
1050 % defined by \cs{NewDocumentCommand} or related.
1051 % \begin{macrocode}
1052 \newbool{VERCMD@this@ltxcmd}
1053 \boolfalse{VERCMD@this@ltxcmd}
1054 % \end{macrocode}
1055
1056 % \DescribeBoolean{VERCMD@failed@ltxcmd} True if any command that failed
1057 % was defined by \cs{NewDocumentCommand} or related.
1058 % \begin{macrocode}
1059 \newbool{VERCMD@failed@ltxcmd}
1060 \boolfalse{VERCMD@failed@ltxcmd}
1061 % \end{macrocode}
1062
1063
1064 % \begin{macro}{\VERCMD@addchanged} \marg{\MDfive sum} \marg{text} \qquad Add to the list of changed definitions.
1065 % \changes{v1.10}{2024/08/25}{Revised summary message.}
1066 % \changes{v1.10}{2024/08/28}{Added `\texttt{*}' if \cs{NewDocumentCommand} or related is used.}
1067 % \begin{macrocode}
1068 \newcommand*{\VERCMD@addchanged}[2]{%
1069 % \end{macrocode}
1070 % Newline control for pretty print.
1071 % \begin{macrocode}
1072 \ifdefempty{\VERCMD@whatchanged}%
1073 {}%
1074 {\apptocmd{\VERCMD@whatchanged}{^^J}{}{}}%
1075 % \end{macrocode}
1076 % ID the message as from \pkg{verifycommand}, add the text,
1077 % add the checksum.
1078 % \begin{macrocode}
1079 \apptocmd{\VERCMD@whatchanged}{%
1080 (verifycommand)\space\space#2^^J%
1081 \space\space\space\space\space\space\space\space\space\space%
1082 \space\space\space\space\space\space\space\space\space(#1)%
1083 }{}{}%
1084 % \end{macrocode}
1085 % Optionally add a |*| after the checksum if the command was
1086 % defined with \cs{NewCommand} or related.
1087 % \begin{macrocode}
1088 \ifbool{VERCMD@this@ltxcmd}{%
1089 \apptocmd{\VERCMD@whatchanged}{ *}{}{}%
1090 \booltrue{VERCMD@failed@ltxcmd}%
1091 }{}%
1092 \boolfalse{VERCMD@this@ltxcmd}%
1093 }
1094 % \end{macrocode}
1095 % \end{macro}
1096
1097 % When the compile is finished, print the accumulated list of changed definitions.
1098 % \changes{v1.10}{2024/08/25}{Revised summary message.}
1099 % ^^A *date
1100 % \begin{macrocode}
1101 \AtEndDocument{
1102 \ifdefempty{\VERCMD@whatchanged}{}{%
1103 \typeout{--------------------------------}%
1104 \typeout{Package verifycommand Warning: Definitions have changed.}%
1105 \typeout{Patches for the following macros may need to be updated.}%
1106 \typeout{See the previous warnings for line numbers.}%
1107 \typeout{}%
1108 \typeout{Syntax:\space\space Patching pkg -> Defining pkg: Macro (checksum)}%
1109 \typeout{-----}%
1110 \typeout{\VERCMD@whatchanged}
1111 \typeout{-----}%
1112 \typeout{Look for updates to these packages.}
1113 %
1114 \ifbool{VERCMD@failed@ltxcmd}{
1115 \typeout{Any of the above marked with a * may be due to changes in LaTeX internals,}
1116 \typeout{the most recently known of which was 2023/12/01.}
1117 \typeout{If so, look for updates for the LaTeX sytem as well.}
1118 }{}
1119 %
1120 \typeout{--------------------------------}
1121 }
1122 }
1123 % \end{macrocode}
1124
1125
1126 % \begin{macro}{\VERCMD@ProgWarning} \marg{text} \qquad Warning without a package name.
1127 % \begin{macrocode}
1128 \def\VERCMD@ProgWarning#1{%
1129 \GenericWarning{%
1130 % (\jobname)\@spaces\@spaces%
1131 \@spaces\@spaces
1132 }{%
1133 Warning: #1%
1134 }%
1135 }
1136 % \end{macrocode}
1137 % \end{macro}
1138
1139
1140 % \begin{macro}{\VERCMDWarning} \marg{yourpackage} \marg{theirpackage} \marg{defn name}
1141 %
1142 % If no package names, print a general warning.
1143 % If package names are given, print a \cs{PackageWarning}.
1144 % Either way, also add to the summary report.
1145 % \changes{v1.10}{2024/08/25}{Revised warning message.}
1146 % \begin{macrocode}
1147 \newcommand*{\VERCMDWarning}[3]{%
1148 \ifblank{#1}%
1149 {%
1150 \VERCMD@ProgWarning{%
1151 A definition has changed:\MessageBreak
1152 \ifblank{#2}{}{#2: }\string#3\MessageBreak
1153 (\VERCMD@temp)\MessageBreak
1154 }%
1155 \expandafter\VERCMD@addchanged%
1156 \expandafter{\VERCMD@temp}{\string#3}%
1157 }%
1158 {%
1159 \PackageWarning{#1}{%
1160 A definition has changed:\MessageBreak%
1161 \ifblank{#2}{}{#2: }%
1162 \string#3\MessageBreak%
1163 (\VERCMD@temp)\MessageBreak%
1164 }%
1165 \expandafter\VERCMD@addchanged%
1166 \expandafter{\VERCMD@temp}{#1 -> \ifblank{#2}{}{#2: }\string#3}%
1167 }%
1168 }
1169 % \end{macrocode}
1170 % \end{macro}
1171 %
1172 %
1173 % \begin{macrocode}
1174 \ExplSyntaxOn
1175 % \end{macrocode}
1176 %
1177 %
1178 %
1179 % \subsection{User interface}
1180 %
1181 %
1182 % \DescribeBoolean{VERCMD@passed} True if any test passed.
1183 % \changes{v1.10}{2024/08/28}{Added test groups.}
1184 % \begin{macrocode}
1185 \newbool{VERCMD@passed}
1186 % \end{macrocode}
1187 %
1188 % \DescribeBoolean{VERCMD@failed} True if any test failed.
1189 % \changes{v1.10}{2024/08/28}{Added test groups.}
1190 % \begin{macrocode}
1191 \newbool{VERCMD@failed}
1192 % \end{macrocode}
1193 %
1194 % \begin{macro}{\TestVerifyCommands}
1195 % Starts a new set of \cs{VerifyCommand} tests,
1196 % after which the booleans will tell if any passed and if any failed.
1197 % \changes{v1.10}{2024/08/28}{Added test groups.}
1198 % \begin{macrocode}
1199 \newcommand*{\TestVerifyCommands}
1200 {
1201 \boolfalse{VERCMD@passed}
1202 \boolfalse{VERCMD@failed}
1203 }
1204 % \end{macrocode}
1205 % \end{macro}
1206 %
1207 % \begin{macro}{\IfVerifyCommandPassed} \marg{true} \marg{false}
1208 % If any of the \cs{VerifyCommand} tests passed, do the |true| clause.
1209 % If none of them passed, do the |false| clause.
1210 % \changes{v1.10}{2024/08/28}{Added test groups.}
1211 % \begin{macrocode}
1212 \newcommand*{\IfVerifyCommandPassed}
1213 {%
1214 \ifbool{VERCMD@passed}%
1215 {\let\VERCMD@tempa\@firstoftwo}%
1216 {\let\VERCMD@tempa\@secondoftwo}%
1217 \VERCMD@tempa%
1218 }
1219 % \end{macrocode}
1220 % \end{macro}
1221 %
1222 % \begin{macro}{\IfVerifyCommandFailed} \marg{true} \marg{false}
1223 % If any of the \cs{VerifyCommand} tests failed, do the |true| clause.
1224 % If none of them failed, do the |false| clause.
1225 % \changes{v1.10}{2024/08/28}{Added test groups.}
1226 % \begin{macrocode}
1227 \newcommand*{\IfVerifyCommandFailed}
1228 {%
1229 \ifbool{VERCMD@failed}%
1230 {\let\VERCMD@tempa\@firstoftwo}%
1231 {\let\VERCMD@tempa\@secondoftwo}%
1232 \VERCMD@tempa%
1233 }
1234 % \end{macrocode}
1235 % \end{macro}
1236 %
1237 % \begin{macro}{\IfVerifyCommand} \oarg{yourpackage} \oarg{theirpackage}
1238 % \marg{\cs{commandname}} \marg{\MDfive\ checksum}
1239 % \marg{true} \marg{false}
1240 % \changes{v1.10}{2024/06/25}{Added conditional tests.}
1241 %
1242 % Test for various kinds of definitions, and convert them to \MDfive\ checksums.
1243 % \begin{macrocode}
1244 \NewDocumentCommand{\IfVerifyCommand}{O{} O{} m m}{%
1245 % \end{macrocode}
1246 %
1247 % Only if the package is enabled:
1248 % \begin{macrocode}
1249 \ifbool{VERCMDenable}{%
1250 % \end{macrocode}
1251 %
1252 % Default to an un-detected definition type:
1253 % \begin{macrocode}
1254 \edef\VERCMD@temp{Unknown~definition}%
1255 % \end{macrocode}
1256 %
1257 % Will become true if found \cs{NewDocumentCommand} or related.
1258 % \begin{macrocode}
1259 \boolfalse{VERCMD@this@ltxcmd}
1260 % \end{macrocode}
1261 %
1262 % For \cs{NewDocumentCommand}, the macro name is ``|\name code|''
1263 % with a space in the middle.
1264 % \begin{macrocode}
1265 % % NewDocumentCommand:
1266 \ifcsdef{\cs_to_str:N #3~code}%
1267 {%
1268 \booltrue{VERCMD@this@ltxcmd}%
1269 \expandafter\VERCMD@mdfive%
1270 \csname \cs_to_str:N #3~code\endcsname%
1271 }%
1272 {%
1273 % \end{macrocode}
1274 %
1275 % For \cs{DeclareRobustCommand} with an optional argument,
1276 % the macro name is ``|\\name |'' with a two backslashes and a trailing space.
1277 % \begin{macrocode}
1278 % % DeclareRobustCommmand with option:
1279 \ifcsdef{\VERCMD@backslash\cs_to_str:N #3~}%
1280 {%
1281 \expandafter\VERCMD@mdfive%
1282 \csname \cs_to_str:N #3~code\endcsname%
1283 }%
1284 {%
1285 % \end{macrocode}
1286 %
1287 % For \cs{DeclareRobustCommand}, the macro name is ``|\name |''
1288 % with a trailing space.
1289 % \begin{macrocode}
1290 % % DeclareRobustCommand:
1291 \ifcsdef{\cs_to_str:N #3~}%
1292 {%
1293 \expandafter\VERCMD@mdfive%
1294 \csname \cs_to_str:N #3~\endcsname%
1295 }%
1296 {%
1297 % \end{macrocode}
1298 %
1299 % For \cs{newcommand} with an option, the macro name is ``|\\name|'',
1300 % with two backslashes.
1301 % \begin{macrocode}
1302 % % newcommand w/ option:
1303 \ifcsdef{\VERCMD@backslash\cs_to_str:N #3}%
1304 {%
1305 \expandafter\VERCMD@mdfive%
1306 \csname %
1307 \VERCMD@backslash%
1308 \cs_to_str:N #3%
1309 \endcsname%
1310 }%
1311 % \end{macrocode}
1312 %
1313 % For \cs{newcommand}, the macro name is ``|\name|''.
1314 %
1315 % If none match, the default unknown definition warning is shown
1316 % in place of the checksum.
1317 % \begin{macrocode}
1318 {%
1319 % % newcommand:
1320 \ifdef{#3}%
1321 {\VERCMD@mdfive#3}%
1322 {}%
1323 }%
1324 }%
1325 }%
1326 }%
1327 % \end{macrocode}
1328 %
1329 % If the checksum matches the expected value, do the following
1330 % |true| clause, else do the following |false| clause.
1331 % Also track the true and false tests for \cs{IfVerifyCommandPassed}
1332 % and \cs{IfVerifyCommandFailed}.
1333 % \changes{v1.10}{2024/08/28}{Added test groups.}
1334 % \begin{macrocode}
1335 \ifdefstring{\VERCMD@temp}{#4}%
1336 {%
1337 \booltrue{VERCMD@passed}%
1338 \let\VERCMD@tempa\@firstoftwo%
1339 }%
1340 {%
1341 \booltrue{VERCMD@failed}%
1342 \let\VERCMD@tempa\@secondoftwo%
1343 }%
1344 }% if package enabled
1345 {\let\VERCMD@tempa\@firstoftwo}% if package not enabled
1346 \VERCMD@tempa%
1347 }
1348 % \end{macrocode}
1349 % \end{macro}
1350 %
1351 %
1352 % \begin{macro}{\VerifyCommand} \oarg{yourpackage} \oarg{theirpackage}
1353 % \marg{\cs{commandname}} \marg{\MDfive\ checksum}
1354 %
1355 % Test for various kinds of definitions, and convert them to \MDfive\ checksums.
1356 % \begin{macrocode}
1357 \NewDocumentCommand{\VerifyCommand}{O{} O{} m m}{%
1358 \ifblank{#1}{% #1 blank
1359 \IfVerifyCommand{#3}{#4}{}{\VERCMDWarning{}{}{#3}}%
1360 }% #1 blank
1361 {% #1 given
1362 \ifblank{#2}{% #2 blank
1363 \IfVerifyCommand[#1]{#3}{#4}{}{\VERCMDWarning{#1}{}{#3}}%
1364 }% #2 blank
1365 {% #2 given
1366 \IfVerifyCommand[#1][#2]{#3}{#4}{}{\VERCMDWarning{#1}{#2}{#3}}%
1367 }% #2 given
1368 }% #1 given
1369 }
1370 % \end{macrocode}
1371 % \end{macro}
1372 %
1373 %
1374 % \begin{macro}{\IfVerifyEnvironmentBegin}
1375 % \oarg{yourpackage} \oarg{theirpackage}
1376 % \marg{\cs{commandname}}
1377 % \marg{begin \MDfive\ checksum}
1378 % \changes{v1.10}{2024/06/25}{Added conditional tests.}
1379 %
1380 % Test the begin section of the environment.
1381 % \begin{macrocode}
1382 \NewDocumentCommand{\IfVerifyEnvironmentBegin}{O{} O{} m m}{%
1383 % \end{macrocode}
1384 %
1385 % Only if the package is enabled:
1386 % \begin{macrocode}
1387 \ifbool{VERCMDenable}{%
1388 % \end{macrocode}
1389 %
1390 % Default to an un-detected definition type:
1391 % \begin{macrocode}
1392 \edef\VERCMD@temp{Unknown~definition}%
1393 % \end{macrocode}
1394 %
1395 % Will become true if found \cs{NewDocumentCommand} or related.
1396 % \begin{macrocode}
1397 \boolfalse{VERCMD@this@ltxcmd}
1398 % \end{macrocode}
1399 %
1400 % For \cs{NewDocumentEnvironment}, the macro name is ``|\environment name code|'' with internal spaces.
1401 % \begin{macrocode}
1402 % % NewDocumentEnvironment:
1403 \ifcsdef{environment~#3~code}%
1404 {%
1405 \booltrue{VERCMD@this@ltxcmd}%
1406 \expandafter\VERCMD@mdfive%
1407 \csname environment~#3~code\endcsname%
1408 }%
1409 {%
1410 % \end{macrocode}
1411 %
1412 % For \cs{newenvironment} with an optional argument,
1413 % the macro name is ``|\\name|'', with two backslashes.
1414 % \begin{macrocode}
1415 % % newenvironment with option:
1416 \ifcsdef{\VERCMD@backslash#3}%
1417 {%
1418 \expandafter\VERCMD@mdfive%
1419 \csname \VERCMD@backslash#3\endcsname%
1420 }%
1421 {%
1422 % \end{macrocode}
1423 %
1424 % For \cs{newenvironment}, the macro name is ``|\name|''.
1425 % \begin{macrocode}
1426 % % newenvironment:
1427 \ifcsdef{#3}%
1428 {\expandafter\VERCMD@mdfive\csname #3\endcsname}%
1429 {}%
1430 }%
1431 }%
1432 % \end{macrocode}
1433 %
1434 % Do the first or second next argument depending on a match:
1435 % \changes{v1.10}{2024/08/28}{Added test groups.}
1436 % \begin{macrocode}
1437 \ifdefstring{\VERCMD@temp}{#4}%
1438 {%
1439 \booltrue{VERCMD@passed}%
1440 \let\VERCMD@tempa\@firstoftwo%
1441 }%
1442 {%
1443 \booltrue{VERCMD@failed}%
1444 \let\VERCMD@tempa\@secondoftwo%
1445 }%
1446 % \end{macrocode}
1447 %
1448 % \begin{macrocode}
1449 }% if package enabled
1450 {\let\VERCMD@tempa\@firstoftwo}% if package not enabled
1451 \VERCMD@tempa%
1452 }
1453 % \end{macrocode}
1454 % \end{macro}
1455 %
1456 %
1457 % \begin{macro}{\IfVerifyEnvironmentEnd}
1458 % \oarg{yourpackage} \oarg{theirpackage}
1459 % \marg{\cs{commandname}}
1460 % \marg{end \MDfive\ checksum}
1461 % \changes{v1.10}{2024/06/25}{Added conditional tests.}
1462 %
1463 % Test the end section of the environment.
1464 % \begin{macrocode}
1465 \NewDocumentCommand{\IfVerifyEnvironmentEnd}{O{} O{} m m}{%
1466 % \end{macrocode}
1467 %
1468 % Only if the package is enabled:
1469 % \begin{macrocode}
1470 \ifbool{VERCMDenable}{%
1471 % \end{macrocode}
1472 %
1473 % Default to an un-detected definition type:
1474 % \begin{macrocode}
1475 \edef\VERCMD@temp{Unknown~definition}%
1476 % \end{macrocode}
1477 %
1478 % Will become true if found \cs{NewDocumentCommand} or related.
1479 % \begin{macrocode}
1480 \boolfalse{VERCMD@this@ltxcmd}
1481 % \end{macrocode}
1482 %
1483 % For \cs{NewDocumentEnvironment}, the ending macro name
1484 % is ``|\environment name end aux |'', with spaces and a trailing space.
1485 % \begin{macrocode}
1486 % % end DocumentEnvironment:
1487 \ifcsdef{environment~#3~end~aux~}%
1488 {%
1489 \booltrue{VERCMD@this@ltxcmd}%
1490 \expandafter\VERCMD@mdfive
1491 \csname environment~#3~end~aux~\endcsname%
1492 }%
1493 {%
1494 % \end{macrocode}
1495 %
1496 % For \cs{newenvironment}, the ending macro name is ``|\endname|''.
1497 % \begin{macrocode}
1498 % % end newenvironment:
1499 \ifcsdef{end#3}%
1500 {%
1501 \expandafter\VERCMD@mdfive%
1502 \csname end#3\endcsname%
1503 }%
1504 {}%
1505 }%
1506 % \end{macrocode}
1507 %
1508 % Do the first or second next argument depending on a match:
1509 % \changes{v1.10}{2024/08/28}{Added test groups.}
1510 % \begin{macrocode}
1511 \ifdefstring{\VERCMD@temp}{#4}%
1512 {%
1513 \booltrue{VERCMD@passed}%
1514 \let\VERCMD@tempa\@firstoftwo%
1515 }%
1516 {%
1517 \booltrue{VERCMD@failed}%
1518 \let\VERCMD@tempa\@secondoftwo%
1519 }%
1520 }% if package enabled
1521 {\let\VERCMD@tempa\@firstoftwo}% if package not enabled
1522 \VERCMD@tempa%
1523 }
1524 % \end{macrocode}
1525 % \end{macro}
1526 %
1527 %
1528 % \begin{macro}{\VerifyEnvironment} \oarg{yourpackage} \oarg{theirpackage}
1529 % \marg{\cs{commandname}}
1530 % \marg{begin \MDfive\ checksum}
1531 % \marg{end \MDfive\ checksum}
1532 %
1533 % Test both the begin and end section of the environment.
1534 % \begin{macrocode}
1535 \NewDocumentCommand{\VerifyEnvironment}{O{} O{} m m m}{%
1536 % begin:
1537 \ifblank{#1}{% #1 blank
1538 \IfVerifyEnvironmentBegin{#3}{#4}%
1539 {}%
1540 {\VERCMDWarning{}{}{#3}}%
1541 }% #1 blank
1542 {% #1 given
1543 \ifblank{#2}{% #2 blank
1544 \IfVerifyEnvironmentBegin[#1]{#3}{#4}%
1545 {}%
1546 {\VERCMDWarning{#1}{}{#3}}%
1547 }% #2 blank
1548 {% #2 given
1549 \IfVerifyEnvironmentBegin[#1][#2]{#3}{#4}%
1550 {}%
1551 {\VERCMDWarning{#1}{#2}{#3}}%
1552 }% #2 given
1553 }% #1 given
1554 % end:
1555 \ifblank{#1}{% #1 blank
1556 \IfVerifyEnvironmentEnd{#3}{#5}%
1557 {}%
1558 {\VERCMDWarning{}{}{(end)#3}}%
1559 }% #1 blank
1560 {% #1 given
1561 \ifblank{#2}{% #2 blank
1562 \IfVerifyEnvironmentEnd[#1]{#3}{#5}%
1563 {}%
1564 {\VERCMDWarning{#1}{}{(end)#3}}%
1565 }% #2 blank
1566 {% #2 given
1567 \IfVerifyEnvironmentEnd[#1][#2]{#3}{#5}%
1568 {}%
1569 {\VERCMDWarning{#1}{#2}{(end)#3}}%
1570 }% #2 given
1571 }% #1 given
1572 }
1573 % \end{macrocode}
1574 % \end{macro}
1575 %
1576 %
1577 % \begin{macrocode}
1578 \ExplSyntaxOff
1579 % \end{macrocode}
1580 %
1581 %
1582 % \subsection{Verify infrastructure}
1583 %
1584 % \changes{v1.10}{2024/08/28}{Tests low-level \cs{NewDocumentCommand} code.}
1585 %
1586 % The low-level infrastructure for \cs{NewDocumentCommand} and related
1587 % may change on occasion, causing a change in the resulting code and
1588 % a verification error for such code.
1589 % The following is done while generating the documentation
1590 % for the \pkg{verifycommand} package,
1591 % and verifies the definitions of the underlying
1592 % infrastructure and issues a warning if any has changed.
1593 %
1594 % In the source for the following, \filenm{ltxcmd.dtx} uses |@@| which is
1595 % replaced by |__cmd|.
1596 %
1597 % (Testing silently occurs here, without adding text to the documentation.)
1598 %
1599 % \ExplSyntaxOn
1600 %
1601 % \TestVerifyCommands
1602 %
1603 % ^^A *checksums
1604 % \VerifyCommand[verifycommand][LaTeX kernel]{\__cmd_declare_cmd_code:Nnn}
1605 % {0911983C176452DDE1F471783F875529}
1606 %
1607 % \VerifyCommand[verifycommand][LaTeX kernel]{\__cmd_declare_cmd_optimized:Nnn}
1608 % {CC1FE1C2D4782317D9E9EB391AD7FFE4}
1609 %
1610 % \VerifyCommand[verifycommand][LaTeX kernel]{\__cmd_declare_cmd_code_aux:Nnn}
1611 % {6675F7AC09F310F6AB963DAA0860BD37}
1612 %
1613 % \VerifyCommand[verifycommand][LaTeX kernel]{\__cmd_declare_cmd_code_expandable:Nnn}
1614 % {8EDCF2A369B6F9CE43280D9118F01383}
1615
1616 % \VerifyCommand[verifycommand][LaTeX kernel]{\__cmd_declare_env_internal:nnnn}
1617 % {7F026120EACC68911B492D09A4B0F537}
1618 %
1619 % \ExplSyntaxOff
1620 %
1621 % \IfVerifyCommandFailed
1622 % {
1623 % \AfterEndDocument{
1624 % \PackageWarningNoLine{verifycommand}{%
1625 % The internals for LaTeX \string\NewCommand\MessageBreak%
1626 % and related have changed.\MessageBreak%
1627 % Update the checksums in verifycommand.dtx\MessageBreak
1628 % at `*checksums', and research when the\MessageBreak
1629 % internals changed and update the date\MessageBreak
1630 % in verifycommand.dtx at `*date'%
1631 % }%
1632 % }
1633 % }
1634 % {}
1635 %
1636 %
1637 % \clearpage
1638 %
1639 % \section{\pkg{verifycommand} package maintenance}
1640 %
1641 % To compile \filenm{verifycommand.sty} and \cs{verifycommand.pdf}
1642 % from \filenm{verifycommand.dtx} and \filenm{verifycommand.ins}:
1643 %
1644 % \begin{sourceverb}
1645 % pdflatex verifycommand.ins
1646 % pdflatex verifycommand.dtx
1647 % pdflatex verifycommand.dtx
1648 % makeindex -s gglo.ist -o verifycommand.gls verifycommand.glo
1649 % splitindex verifycommand.idx -- -s gind.ist
1650 % pdflatex verifycommand.dtx
1651 % pdflatex verifycommand.dtx
1652 % \end{sourceverb}
1653 %
1654 %
1655 % \iffalse
1656 %</package>
1657 % \fi
1658 %
1659 %
1660 %
1661 %
1662 %
1663 % \clearpage
1664 % \pagestyle{plain}
1665 %
1666 % \renewcommand{\partname}{}
1667 % \renewcommand{\thepart}{}
1668 % ^^A \part{Change History and Index}
1669 %
1670 %
1671 % \Finale
1672 %
1673 \endinput