Debian Codegraph @

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

raw
1 %%% ====================================================================
2 %%% @LaTeX-file{
3 % filename = "cmdtrack.dtx",
4 %%% filename = "cmdtrack.sty",
5 %%% version = "1.06",
6 %%% date = "2012/12/18",
7 %%% author = "Michael John Downes",
8 %%% copyright = "Copyright 1999 Michael John Downes.
9 %%% Copyright 2012 TeX Users Group.
10 %%% This work may be distributed and/or modified under the
11 %%% conditions of the LaTeX Project Public License, either version 1
12 %%% of this license or (at your option) any later version.
13 %%% The latest version of this license is in
14 %%% http://www.latex-project.org/lppl.txt
15 %%% and version 1.3 or later is part of all distributions of LaTeX
16 %%% version 2003/12/01 or later.
17 %%% ",
18 % keywords = "newcommand",
19 % abstract = "This is a LaTeX package that aids in the task
20 % of checking whether a command defined in a
21 % document preamble is actually used somewhere
22 % in the document.",
23 %%% }
24 %%% ====================================================================
25 % \iffalse
26 %<*driver>
27 \NeedsTeXFormat{LaTeX2e}
28 \documentclass{amsdtx}
29 \begin{document}
30 \title{The \pkg{cmdtrack} package}
31 \author{Michael Downes}
32 \date{Version \fileversion, \filedate}
33 \hDocInput{cmdtrack.dtx}
34 \end{document}
35 %</driver>
36 % \fi
37 %
38 % \maketitle
39 % \section{Introduction}
40 % This package is released under the \LaTeX\ Project Public License.
41 %
42 % The \pkg{cmdtrack} package aids in the task of checking whether a
43 % command defined in a document preamble is actually used somewhere
44 % in the document. If you add a statement
45 % \begin{verbatim}
46 % \usepackage{cmdtrack}
47 % \end{verbatim}
48 % in the preamble of your document, all \cs{newcommand} and similar
49 % statements between that point and \verb'\begin{document}' will be
50 % marked for logging. At the end of the document a report of the
51 % command usage will be printed in the \TeX{} log, for example:
52 % \begin{verbatim}
53 % "mdash" was used on line 25
54 % "ndash" was never used
55 % "gar " was used on line 26
56 % "math character ?" was used on line 26
57 % \end{verbatim}
58 % In this list, a command \cn{foo} is normally listed as
59 % \verb'"foo"'; however if it was defined with an optional argument,
60 % it will be listed as \verb'"\foo"', and if defined with
61 % \cn{DeclareRobustCommand} it will be listed as
62 % \texttt{"foo\symbol{32}"} (with an extra space). This has to do
63 % with the way \latex/ deals with such definitions behind the scenes.
64 % Twiddling the behavior to get more consistent treatment of the
65 % command names looked hard, so I didn't do it. If you can send
66 % actual code to remedy this deficiency, it will be welcome. I do not
67 % plan on trying to fix it myself until after I have dealt with all
68 % the other, more interesting or more pressing, problems in my queue.
69 %
70 % Certain kinds of commands are inherently untrackable due to the way
71 % they are used (counters, lengths, and other variables that may
72 % appear on the right-hand of an assignment statement; commands whose
73 % first use is in the argument of \cs{label}, and so on.) Tracking
74 % for commands of this sort can be turned off by moving their
75 % definitions earlier (before the load statement of the cmdtrack
76 % package), or by listing them in the argument of an \cs{untrack}
77 % statement at the end of your document preamble, for example:
78 % \begin{verbatim}
79 % \untrack{\foo,\bar,\blub,...}
80 % \end{verbatim}
81 %
82 % \section{Limitations}
83 % \begin{itemize}
84 % \item Only commands defined with \cs{newcommand}, \cs{newenvironment},
85 % \cs{newtheorem}, \cs{DeclareMathSymbol}, \cs{DeclareMathOperator},
86 % and their variants are logged. Commands will not be logged if they
87 % are defined with \cs{def} instead of \cs{newcommand},
88 % \cs{mathchardef} instead of \cs{DeclareMathSymbol}, etc.
89 %
90 % \item \qq{Commands} defined with \cs{newlength}, \cs{newsavebox},
91 % \cs{newcounter}, \cs{newcount}, \cs{newtoks}, etc., will not be
92 % logged because it cannot be done without disrupting their normal
93 % use.
94 %
95 % \item Commands defined with \cs{DeclareTextSymbol},
96 % \cs{DeclareTextAccent}, \cs{DeclareMathRadical},
97 % \cs{DeclareMathAlphabet}, and various other things will not be
98 % logged because I was starting to doze off on the keyboard after
99 % adding the support for \cs{DeclareMathSymbol}. Any volunteers?
100 %
101 % \item The definitions of the commands that are to be logged must fall
102 % between \verb'\usepackage{cmdtrack}' and \verb'\begin{document}'.
103 % For problem commands, try moving their definitions before the
104 % \verb'\usepackage{cmdtrack}' line, or use the \cs{untrack} command
105 % to cancel tracking for selected commands at the end of the
106 % preamble.
107 %
108 % \item The \pkg{cmdtrack} package should be the last package loaded
109 % (or, the later-loaded packages will have their commands tracked as
110 % well, if that is what you want).
111 %
112 % \item A command definition starting with \cs{multicolumn} will cause
113 % trouble (unless it is never used).
114 %
115 % \item Large number of \cs{newcommands} (200+, say) might lead to an
116 % error message \qq{\TeX{} capacity exceeded (hash size \ldots)}.
117 % Depends on the capacity of your \TeX{} system.
118 %
119 % \end{itemize}
120 %
121 % \StopEventually{}
122 %
123 % \section{Embedded documentation}
124 %
125 % The following material comes into play only when the \verb'?'
126 % package option is used.
127 %
128 % \begin{macrocode}
129 %% Self-documenting section
130 \ifcat ?$\relax{\catcode37=7 \catcode127=9 \def\0{\@sanitize\catcode}\fi
131 %%? \endlinechar125\catcode127=13\def%%?{\typeout}\037=7
132 %%?{====================================================================
133 %%?{ With the cmdtrack package, all commands and environments defined
134 %%?{ between \usepackage{cmdtrack} and \begin{document} will be marked
135 %%?{ for logging. A report on the usage of the marked commands will be
136 %%?{ printed in the LaTeX log file. Standard LaTeX methods must be used
137 %%?{ for defining the commands (things defined with \def, for example,
138 %%?{ won't be logged). Use \untrack{\cmd,\othercmd,...} just before
139 %%?{ \begin{document} to turn off tracking for selected commands.
140 %%?{
141 %%?{ Package options:
142 %%?{
143 %%?{ ? Causes this information to be shown on-screen.
144 %%?{
145 %%?{ morose Opposite of verbose: causes the brief message about the ?
146 %%?{ option to be suppressed.
147 %%?{
148 %%?{ Support for the following is not [yet] provided:
149 %%?{ \DeclareTextSymbol, \DeclareMathRadical, \DeclareMathAlphabet, and
150 %%?{ some others.
151 %%?{
152 %%?{ More comprehensive documentation for cmdtrack.sty may be found in
153 %%?{ cmdtrack.dtx.
154 %%?{====================================================================
155 %%?{}}\endinput\bgroup
156 %%
157 % \end{macrocode}
158 %
159 % \section{Implementation}
160 % Standard declaration of package name and date.
161 % \begin{macrocode}
162 \NeedsTeXFormat{LaTeX2e}
163 \ProvidesPackage{cmdtrack}[2012/12/18 v1.06]
164 % \end{macrocode}
165 %
166 % The \pkg{cmdtrack} package works by hooking into the internal
167 % \LaTeX{} function \cs{@yargdef}. When processing something like
168 % \verb'\newcommand{\foo}{...}', there is a point where \LaTeX{}
169 % runs, essentially,
170 % \begin{verbatim}
171 % \def\foo{...}
172 % \end{verbatim}
173 % Just as \LaTeX{} is about to carry out that assignment, we jump
174 % in and substitute a different control sequence in place of
175 % \cs{foo}! Our substituted control sequence has the same name but
176 % with an extra double-quote character \verb'"' added at the
177 % beginning: i.e., \verb'\"foo' instead of \cs{foo}. Thus \cs{"foo}
178 % gets the real definition, and we are free to give \cs{foo} some
179 % other definition for logging purposes. Obviously it should end by
180 % calling the real definition. And here is how we arrange that.
181 %
182 % \begin{enumerate}
183 % \item \cs{foo} expands to \verb'\logcmd \"foo \foo'.
184 %
185 % \item \cs{logcmd} redefines \cs{foo} to take on the meaning of
186 % \cs{"foo}.
187 %
188 % \item \cs{logcmd} adds \cs{"foo} to a used-commands list, and records
189 % the current line number with it.
190 % \end{enumerate}
191 %
192 % Then when we reach the end of our document, we need to find some
193 % way of looking through all of our marked commands and reporting
194 % which ones were used. During the processing of the preamble, the
195 % marked commands were stored in a list \cs{commandlist}.
196 % Furthermore, when \cs{logcmd} redefined \cs{"foo}, it put in a
197 % special marker character along with the line number. Then when we
198 % reach the end of our document, we can iterate over the command list
199 % with a function that checks for that special character in the
200 % \cs{meaning} of each command.
201 %
202 % Alternatively one could imagine adding the used commands to a
203 % separate list. At one point I started doing that but it got a
204 % little messy so I abandoned the idea. Besides, this way the report
205 % comes out with the commands in the same order as they were defined
206 % in the preamble (except that newtheorem commands gravitate toward
207 % the end of the list).
208 %
209 % \begin{macrocode}
210 \let\commandlist\@empty
211 % \end{macrocode}
212 %
213 % \begin{macrocode}
214 \AtEndDocument{\report@command@usage}
215 % \end{macrocode}
216 %
217 % The \LaTeX{} kernel doesn't provide this.
218 % \begin{macrocode}
219 \edef\@quotechar{\string"}
220 % \end{macrocode}
221 %
222 % The \cs{untrack} command could just redefine \cs{logcmd} and run
223 % through its argument list, but if the user accidentally leaves in
224 % some command that is no longer defined (or defined before the
225 % \pkg{cmdtrack} package is loaded) then some kind of error is
226 % likely. So we check specifically for the string \verb"\logcmd" at
227 % the beginning of each command's \cs{meaning} string.
228 % \begin{macrocode}
229 \newcommand{\untrack}[1]{%
230 \begingroup
231 \def\logcmd##1##2{\global\let##1=##2%
232 \xdef##2{\@percentchar\the\inputlineno}%
233 }%
234 \untrack@a#1{,\@gobble}\endgroup
235 }
236 % \end{macrocode}
237 %
238 % \begin{macrocode}i
239 \def\untrack@a#1{%
240 \ifx,#1\@gobbletwo\expandafter\@gobble
241 \else \expandafter\untrack@b\meaning#1\@nil#1%
242 \fi
243 \untrack@a
244 }
245 % \end{macrocode}
246 %
247 % \begin{macrocode}
248 \def\untrack@b#1->#2#3#4#5#6#7#8#9\@nil{%
249 \expandafter\ifx\csname #3#4#5@#6#7#8\endcsname\log@cmd
250 \else
251 \def\@tempa##1{%
252 \PackageWarningNoLine{cmdtrack}{%
253 Command \protect##1 does not have tracking turned on}%
254 }%
255 \expandafter\@tempa
256 \fi
257 }
258 % \end{macrocode}
259 %
260 % One branch of providecommand processing uses \cs{reserved@a} in a
261 % way that will fail unless we watch out for it.
262 % \begin{macrocode}
263 \def\@isreserved@a#1\reserved@a#2#3@{#2}
264 % \end{macrocode}
265 %
266 % \begin{macrocode}
267 \let\@hash@\relax
268 \def\log@cmd#1#2{%
269 \if\@isreserved@a#2T\reserved@a F@T%
270 \endgroup
271 \else
272 \toks@\expandafter{\commandlist#1}%
273 \xdef\commandlist{\the\toks@}%
274 \endgroup
275 \def#2{\logcmd#2#1}%
276 \fi
277 \let\@hash@##%
278 \l@ngrel@x\expandafter\def\expandafter#1\reserved@a
279 }
280 % \end{macrocode}
281 %
282 % \begin{macrocode}
283 \def\logcmd#1#2{%
284 \ifx\protect\@typeset@protect
285 \global\let#1#2%
286 \xdef#2{\@percentchar\the\inputlineno}%
287 \else
288 \expandafter\protect
289 \fi
290 #1%
291 }
292 % \end{macrocode}
293 %
294 % \begin{macrocode}
295 \begingroup \catcode`\"=12
296 \gdef\cmd@check#1->#2#3-#4\@nil#5{%
297 \if\@percentchar#2\typeout{\string#5" was used on line #3}%
298 \else\typeout{\string#5" was never used}%
299 \fi
300 }
301 \endgroup
302 % \end{macrocode}
303 %
304 % \begin{macrocode}
305 \def\report@command@usage{%
306 \def\@tempa{\typeout{=========================================}}%
307 \@tempa
308 \begingroup \escapechar\m@ne
309 \def\do##1{%
310 \ifx\advance##1\expandafter\@gobbletwo\fi
311 {\expandafter\cmd@check\meaning##1->@-\@nil##1}%
312 \do
313 }%
314 \expandafter\do\commandlist \advance\z@\z@
315 \endgroup
316 \@tempa
317 }
318 % \end{macrocode}
319 %
320 % \begin{macrocode}
321 \def\testthm#1{%
322 \expandafter\testthm@a\csname#1\expandafter\endcsname
323 \csname\@quotechar#1\endcsname
324 }
325 % \end{macrocode}
326 %
327 % In order to avoid figuring out how to read the optional arguments
328 % of \cs{newtheorem}, we postpone the application of \cs{log@cmd}
329 % (actually, a slight variation thereof) until
330 % \verb'\begin{document}'.
331 % \begin{macrocode}
332 \let\old@newtheorem\newtheorem
333 \def\newtheorem#1{%
334 \AtBeginDocument{\testthm{#1}}%
335 \old@newtheorem{#1}%
336 }
337 % \end{macrocode}
338 %
339 % \begin{macrocode}
340 \def\testthm@a#1#2{%
341 \begingroup
342 \toks@\expandafter{\commandlist#2}%
343 \xdef\commandlist{\the\toks@}%
344 \endgroup
345 \let#2#1%
346 \def#1{\logcmd#1#2}%
347 }
348 % \end{macrocode}
349 %
350 % It would be unusual for a character to be defined as a math symbol
351 % in a document preamble. But what hey, why not support it?
352 % \begin{macrocode}
353 \def\set@mathchar#1#2#3#4{%
354 \expandafter\set@mathchar@a
355 \csname\@quotechar math character \string#2\expandafter\endcsname
356 \expandafter{\number`#2}{#1}{#3}{#4}%
357 }%
358 % \end{macrocode}
359 %
360 % \begin{macrocode}
361 \def\set@mathchar@a#1#2#3#4#5{%
362 \global\mathcode#2=\@quotechar 8000
363 \global\mathchardef#1\@quotechar\mathchar@type#4\hexnumber@#3#5\relax
364 \toks@\expandafter{\commandlist#1}%
365 \xdef\commandlist{\the\toks@}%
366 \begingroup \lccode`\.=#2\lccode`\~=#2\lowercase{\endgroup
367 \gdef~{\global\mathcode#2=#1\logcmd#1#1}}%
368 }
369 % \end{macrocode}
370 %
371 % \begin{macrocode}
372 \def\set@mathsymbol#1#2#3#4{%
373 \begingroup \escapechar=`\"\relax
374 \global\expandafter\mathchardef
375 \csname\string#2\endcsname
376 \@quotechar\mathchar@type#3\hexnumber@#1#4\relax
377 \expandafter\log@cmd@a\csname\string#2\endcsname#2%
378 }
379 % \end{macrocode}
380 %
381 % \begin{macrocode}
382 \def\set@mathaccent#1#2#3#4{%
383 \xdef#2{\mathaccent\@quotechar\mathchar@type#3\hexnumber@#1#4\relax}%
384 \begingroup \escapechar`\"\relax
385 \expandafter\log@cmd@a\csname\string#2\endcsname#2%
386 }
387 % \end{macrocode}
388 %
389 % Note the use of \cs{gdef}.
390 % \begin{macrocode}
391 \def\log@cmd@a#1#2{%
392 \toks@\expandafter{\commandlist#1}%
393 \xdef\commandlist{\the\toks@}%
394 \endgroup
395 \gdef#2{\logcmd#2#1}%
396 }
397 % \end{macrocode}
398 %
399 % \begin{macrocode}
400 \DeclareOption{?}{\AtEndOfPackage{\ShowPackageInfo{cmdtrack}}}
401 % \end{macrocode}
402 %
403 % \begin{macrocode}
404 \DeclareOption{morose}{}
405 % \end{macrocode}
406 %
407 % \begin{macrocode}
408 \DeclareOption{simple}{%
409 \def\logcmd#1#2{%
410 \ifx\protect\@typeset@protect
411 \global\let#1#2%
412 \begingroup \escapechar\m@ne
413 \typeout{\string#2\string" was used on line \the\inputlineno}%
414 \endgroup
415 \else
416 \expandafter\protect
417 \fi
418 #1%
419 }%
420 \AtBeginDocument{\global\let\commandlist\@empty}%
421 \global\let\report@command@usage\relax
422 }
423 % \end{macrocode}
424 %
425 % \begin{macrocode}
426 \ProcessOptions\relax
427 \begingroup
428 \catcode`\%=9 \catcode`\&=14 \catcode`\"=12
429 \@ifpackagewith{cmdtrack}{morose}{\catcode`\%=14 }{}
430 \@ifpackagewith{cmdtrack}{?}{\catcode`\%=14 }{}
431 %%\typeout{&
432 %%Try "\string\usepackage[\string ?]{cmdtrack}"
433 %%to see information on using this package^^J&
434 %%[including how to turn off this "helpful" message].&
435 %%}
436 \endgroup
437 % \end{macrocode}
438 %
439 % \begin{macrocode}
440 \newcommand{\ShowPackageInfo}[1]{%
441 \begingroup \catcode`\?=3
442 \input{#1.\@pkgextension}%
443 \endgroup
444 }
445 % \end{macrocode}
446 %
447 % \begin{macrocode}
448 \let\@@yargdef\@yargdef
449 % \end{macrocode}
450 %
451 % Restore \cs{@yargdef} to normal at beginning of document, so that uses of
452 % \cs{newcommand} in \cs{maketitle} (e.g.\@) are ignored.
453 % \begin{macrocode}
454 \AtBeginDocument{\let\@yargdef\@@yargdef}
455 % \end{macrocode}
456 %
457 % \begin{macrocode}
458 \let\@hash@\relax
459 \def\@yargdef #1#2#3{%
460 \@tempcnta#3\relax \advance\@tempcnta\@ne \let\@hash@\relax
461 \edef\reserved@a{\ifx#2\tw@ [\@hash@ 1]\fi}%
462 \@tempcntb#2%
463 \@whilenum\@tempcntb<\@tempcnta\do{%
464 \edef\reserved@a{\reserved@a\@hash@\the\@tempcntb}%
465 \advance\@tempcntb\@ne
466 }%
467 \begingroup \escapechar=`\"\relax
468 \expandafter\log@cmd\csname\string#1\endcsname#1%
469 }
470 % \end{macrocode}
471 %
472 % The usual \cs{endinput} to ensure that random garbage at the end of
473 % the file doesn't get copied by \fn{docstrip}.
474 % \begin{macrocode}
475 \endinput
476 % \end{macrocode}
477 %
478 % \Finale