%%% ====================================================================
%%% @LaTeX-file{
% filename = "cmdtrack.dtx",
%%% filename = "cmdtrack.sty",
%%% version = "1.06",
%%% date = "2012/12/18",
%%% author = "Michael John Downes",
%%% copyright = "Copyright 1999 Michael John Downes.
%%% Copyright 2012 TeX Users Group.
%%% This work may be distributed and/or modified under the
%%% conditions of the LaTeX Project Public License, either version 1
%%% of this license or (at your option) any later version.
%%% The latest version of this license is in
%%% http://www.latex-project.org/lppl.txt
%%% and version 1.3 or later is part of all distributions of LaTeX
%%% version 2003/12/01 or later.
%%% ",
% keywords = "newcommand",
% abstract = "This is a LaTeX package that aids in the task
% of checking whether a command defined in a
% document preamble is actually used somewhere
% in the document.",
%%% }
%%% ====================================================================
% \iffalse
%<*driver>
\NeedsTeXFormat{LaTeX2e}
\documentclass{amsdtx}
\begin{document}
\title{The \pkg{cmdtrack} package}
\author{Michael Downes}
\date{Version \fileversion, \filedate}
\hDocInput{cmdtrack.dtx}
\end{document}
%</driver>
% \fi
%
% \maketitle
% \section{Introduction}
% This package is released under the \LaTeX\ Project Public License.
%
% The \pkg{cmdtrack} package aids in the task of checking whether a
% command defined in a document preamble is actually used somewhere
% in the document. If you add a statement
% \begin{verbatim}
% \usepackage{cmdtrack}
% \end{verbatim}
% in the preamble of your document, all \cs{newcommand} and similar
% statements between that point and \verb'\begin{document}' will be
% marked for logging. At the end of the document a report of the
% command usage will be printed in the \TeX{} log, for example:
% \begin{verbatim}
% "mdash" was used on line 25
% "ndash" was never used
% "gar " was used on line 26
% "math character ?" was used on line 26
% \end{verbatim}
% In this list, a command \cn{foo} is normally listed as
% \verb'"foo"'; however if it was defined with an optional argument,
% it will be listed as \verb'"\foo"', and if defined with
% \cn{DeclareRobustCommand} it will be listed as
% \texttt{"foo\symbol{32}"} (with an extra space). This has to do
% with the way \latex/ deals with such definitions behind the scenes.
% Twiddling the behavior to get more consistent treatment of the
% command names looked hard, so I didn't do it. If you can send
% actual code to remedy this deficiency, it will be welcome. I do not
% plan on trying to fix it myself until after I have dealt with all
% the other, more interesting or more pressing, problems in my queue.
%
% Certain kinds of commands are inherently untrackable due to the way
% they are used (counters, lengths, and other variables that may
% appear on the right-hand of an assignment statement; commands whose
% first use is in the argument of \cs{label}, and so on.) Tracking
% for commands of this sort can be turned off by moving their
% definitions earlier (before the load statement of the cmdtrack
% package), or by listing them in the argument of an \cs{untrack}
% statement at the end of your document preamble, for example:
% \begin{verbatim}
% \untrack{\foo,\bar,\blub,...}
% \end{verbatim}
%
% \section{Limitations}
% \begin{itemize}
% \item Only commands defined with \cs{newcommand}, \cs{newenvironment},
% \cs{newtheorem}, \cs{DeclareMathSymbol}, \cs{DeclareMathOperator},
% and their variants are logged. Commands will not be logged if they
% are defined with \cs{def} instead of \cs{newcommand},
% \cs{mathchardef} instead of \cs{DeclareMathSymbol}, etc.
%
% \item \qq{Commands} defined with \cs{newlength}, \cs{newsavebox},
% \cs{newcounter}, \cs{newcount}, \cs{newtoks}, etc., will not be
% logged because it cannot be done without disrupting their normal
% use.
%
% \item Commands defined with \cs{DeclareTextSymbol},
% \cs{DeclareTextAccent}, \cs{DeclareMathRadical},
% \cs{DeclareMathAlphabet}, and various other things will not be
% logged because I was starting to doze off on the keyboard after
% adding the support for \cs{DeclareMathSymbol}. Any volunteers?
%
% \item The definitions of the commands that are to be logged must fall
% between \verb'\usepackage{cmdtrack}' and \verb'\begin{document}'.
% For problem commands, try moving their definitions before the
% \verb'\usepackage{cmdtrack}' line, or use the \cs{untrack} command
% to cancel tracking for selected commands at the end of the
% preamble.
%
% \item The \pkg{cmdtrack} package should be the last package loaded
% (or, the later-loaded packages will have their commands tracked as
% well, if that is what you want).
%
% \item A command definition starting with \cs{multicolumn} will cause
% trouble (unless it is never used).
%
% \item Large number of \cs{newcommands} (200+, say) might lead to an
% error message \qq{\TeX{} capacity exceeded (hash size \ldots)}.
% Depends on the capacity of your \TeX{} system.
%
% \end{itemize}
%
% \StopEventually{}
%
% \section{Embedded documentation}
%
% The following material comes into play only when the \verb'?'
% package option is used.
%
% \begin{macrocode}
%% Self-documenting section
\ifcat ?$\relax{\catcode37=7 \catcode127=9 \def\0{\@sanitize\catcode}\fi
%%? \endlinechar125\catcode127=13\def%%?{\typeout}\037=7
%%?{====================================================================
%%?{ With the cmdtrack package, all commands and environments defined
%%?{ between \usepackage{cmdtrack} and \begin{document} will be marked
%%?{ for logging. A report on the usage of the marked commands will be
%%?{ printed in the LaTeX log file. Standard LaTeX methods must be used
%%?{ for defining the commands (things defined with \def, for example,
%%?{ won't be logged). Use \untrack{\cmd,\othercmd,...} just before
%%?{ \begin{document} to turn off tracking for selected commands.
%%?{
%%?{ Package options:
%%?{
%%?{ ? Causes this information to be shown on-screen.
%%?{
%%?{ morose Opposite of verbose: causes the brief message about the ?
%%?{ option to be suppressed.
%%?{
%%?{ Support for the following is not [yet] provided:
%%?{ \DeclareTextSymbol, \DeclareMathRadical, \DeclareMathAlphabet, and
%%?{ some others.
%%?{
%%?{ More comprehensive documentation for cmdtrack.sty may be found in
%%?{ cmdtrack.dtx.
%%?{====================================================================
%%?{}}\endinput\bgroup
%%
% \end{macrocode}
%
% \section{Implementation}
% Standard declaration of package name and date.
% \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{cmdtrack}[2012/12/18 v1.06]
% \end{macrocode}
%
% The \pkg{cmdtrack} package works by hooking into the internal
% \LaTeX{} function \cs{@yargdef}. When processing something like
% \verb'\newcommand{\foo}{...}', there is a point where \LaTeX{}
% runs, essentially,
% \begin{verbatim}
% \def\foo{...}
% \end{verbatim}
% Just as \LaTeX{} is about to carry out that assignment, we jump
% in and substitute a different control sequence in place of
% \cs{foo}! Our substituted control sequence has the same name but
% with an extra double-quote character \verb'"' added at the
% beginning: i.e., \verb'\"foo' instead of \cs{foo}. Thus \cs{"foo}
% gets the real definition, and we are free to give \cs{foo} some
% other definition for logging purposes. Obviously it should end by
% calling the real definition. And here is how we arrange that.
%
% \begin{enumerate}
% \item \cs{foo} expands to \verb'\logcmd \"foo \foo'.
%
% \item \cs{logcmd} redefines \cs{foo} to take on the meaning of
% \cs{"foo}.
%
% \item \cs{logcmd} adds \cs{"foo} to a used-commands list, and records
% the current line number with it.
% \end{enumerate}
%
% Then when we reach the end of our document, we need to find some
% way of looking through all of our marked commands and reporting
% which ones were used. During the processing of the preamble, the
% marked commands were stored in a list \cs{commandlist}.
% Furthermore, when \cs{logcmd} redefined \cs{"foo}, it put in a
% special marker character along with the line number. Then when we
% reach the end of our document, we can iterate over the command list
% with a function that checks for that special character in the
% \cs{meaning} of each command.
%
% Alternatively one could imagine adding the used commands to a
% separate list. At one point I started doing that but it got a
% little messy so I abandoned the idea. Besides, this way the report
% comes out with the commands in the same order as they were defined
% in the preamble (except that newtheorem commands gravitate toward
% the end of the list).
%
% \begin{macrocode}
\let\commandlist\@empty
% \end{macrocode}
%
% \begin{macrocode}
\AtEndDocument{\report@command@usage}
% \end{macrocode}
%
% The \LaTeX{} kernel doesn't provide this.
% \begin{macrocode}
\edef\@quotechar{\string"}
% \end{macrocode}
%
% The \cs{untrack} command could just redefine \cs{logcmd} and run
% through its argument list, but if the user accidentally leaves in
% some command that is no longer defined (or defined before the
% \pkg{cmdtrack} package is loaded) then some kind of error is
% likely. So we check specifically for the string \verb"\logcmd" at
% the beginning of each command's \cs{meaning} string.
% \begin{macrocode}
\newcommand{\untrack}[1]{%
\begingroup
\def\logcmd##1##2{\global\let##1=##2%
\xdef##2{\@percentchar\the\inputlineno}%
}%
\untrack@a#1{,\@gobble}\endgroup
}
% \end{macrocode}
%
% \begin{macrocode}i
\def\untrack@a#1{%
\ifx,#1\@gobbletwo\expandafter\@gobble
\else \expandafter\untrack@b\meaning#1\@nil#1%
\fi
\untrack@a
}
% \end{macrocode}
%
% \begin{macrocode}
\def\untrack@b#1->#2#3#4#5#6#7#8#9\@nil{%
\expandafter\ifx\csname #3#4#5@#6#7#8\endcsname\log@cmd
\else
\def\@tempa##1{%
\PackageWarningNoLine{cmdtrack}{%
Command \protect##1 does not have tracking turned on}%
}%
\expandafter\@tempa
\fi
}
% \end{macrocode}
%
% One branch of providecommand processing uses \cs{reserved@a} in a
% way that will fail unless we watch out for it.
% \begin{macrocode}
\def\@isreserved@a#1\reserved@a#2#3@{#2}
% \end{macrocode}
%
% \begin{macrocode}
\let\@hash@\relax
\def\log@cmd#1#2{%
\if\@isreserved@a#2T\reserved@a F@T%
\endgroup
\else
\toks@\expandafter{\commandlist#1}%
\xdef\commandlist{\the\toks@}%
\endgroup
\def#2{\logcmd#2#1}%
\fi
\let\@hash@##%
\l@ngrel@x\expandafter\def\expandafter#1\reserved@a
}
% \end{macrocode}
%
% \begin{macrocode}
\def\logcmd#1#2{%
\ifx\protect\@typeset@protect
\global\let#1#2%
\xdef#2{\@percentchar\the\inputlineno}%
\else
\expandafter\protect
\fi
#1%
}
% \end{macrocode}
%
% \begin{macrocode}
\begingroup \catcode`\"=12
\gdef\cmd@check#1->#2#3-#4\@nil#5{%
\if\@percentchar#2\typeout{\string#5" was used on line #3}%
\else\typeout{\string#5" was never used}%
\fi
}
\endgroup
% \end{macrocode}
%
% \begin{macrocode}
\def\report@command@usage{%
\def\@tempa{\typeout{=========================================}}%
\@tempa
\begingroup \escapechar\m@ne
\def\do##1{%
\ifx\advance##1\expandafter\@gobbletwo\fi
{\expandafter\cmd@check\meaning##1->@-\@nil##1}%
\do
}%
\expandafter\do\commandlist \advance\z@\z@
\endgroup
\@tempa
}
% \end{macrocode}
%
% \begin{macrocode}
\def\testthm#1{%
\expandafter\testthm@a\csname#1\expandafter\endcsname
\csname\@quotechar#1\endcsname
}
% \end{macrocode}
%
% In order to avoid figuring out how to read the optional arguments
% of \cs{newtheorem}, we postpone the application of \cs{log@cmd}
% (actually, a slight variation thereof) until
% \verb'\begin{document}'.
% \begin{macrocode}
\let\old@newtheorem\newtheorem
\def\newtheorem#1{%
\AtBeginDocument{\testthm{#1}}%
\old@newtheorem{#1}%
}
% \end{macrocode}
%
% \begin{macrocode}
\def\testthm@a#1#2{%
\begingroup
\toks@\expandafter{\commandlist#2}%
\xdef\commandlist{\the\toks@}%
\endgroup
\let#2#1%
\def#1{\logcmd#1#2}%
}
% \end{macrocode}
%
% It would be unusual for a character to be defined as a math symbol
% in a document preamble. But what hey, why not support it?
% \begin{macrocode}
\def\set@mathchar#1#2#3#4{%
\expandafter\set@mathchar@a
\csname\@quotechar math character \string#2\expandafter\endcsname
\expandafter{\number`#2}{#1}{#3}{#4}%
}%
% \end{macrocode}
%
% \begin{macrocode}
\def\set@mathchar@a#1#2#3#4#5{%
\global\mathcode#2=\@quotechar 8000
\global\mathchardef#1\@quotechar\mathchar@type#4\hexnumber@#3#5\relax
\toks@\expandafter{\commandlist#1}%
\xdef\commandlist{\the\toks@}%
\begingroup \lccode`\.=#2\lccode`\~=#2\lowercase{\endgroup
\gdef~{\global\mathcode#2=#1\logcmd#1#1}}%
}
% \end{macrocode}
%
% \begin{macrocode}
\def\set@mathsymbol#1#2#3#4{%
\begingroup \escapechar=`\"\relax
\global\expandafter\mathchardef
\csname\string#2\endcsname
\@quotechar\mathchar@type#3\hexnumber@#1#4\relax
\expandafter\log@cmd@a\csname\string#2\endcsname#2%
}
% \end{macrocode}
%
% \begin{macrocode}
\def\set@mathaccent#1#2#3#4{%
\xdef#2{\mathaccent\@quotechar\mathchar@type#3\hexnumber@#1#4\relax}%
\begingroup \escapechar`\"\relax
\expandafter\log@cmd@a\csname\string#2\endcsname#2%
}
% \end{macrocode}
%
% Note the use of \cs{gdef}.
% \begin{macrocode}
\def\log@cmd@a#1#2{%
\toks@\expandafter{\commandlist#1}%
\xdef\commandlist{\the\toks@}%
\endgroup
\gdef#2{\logcmd#2#1}%
}
% \end{macrocode}
%
% \begin{macrocode}
\DeclareOption{?}{\AtEndOfPackage{\ShowPackageInfo{cmdtrack}}}
% \end{macrocode}
%
% \begin{macrocode}
\DeclareOption{morose}{}
% \end{macrocode}
%
% \begin{macrocode}
\DeclareOption{simple}{%
\def\logcmd#1#2{%
\ifx\protect\@typeset@protect
\global\let#1#2%
\begingroup \escapechar\m@ne
\typeout{\string#2\string" was used on line \the\inputlineno}%
\endgroup
\else
\expandafter\protect
\fi
#1%
}%
\AtBeginDocument{\global\let\commandlist\@empty}%
\global\let\report@command@usage\relax
}
% \end{macrocode}
%
% \begin{macrocode}
\ProcessOptions\relax
\begingroup
\catcode`\%=9 \catcode`\&=14 \catcode`\"=12
\@ifpackagewith{cmdtrack}{morose}{\catcode`\%=14 }{}
\@ifpackagewith{cmdtrack}{?}{\catcode`\%=14 }{}
%%\typeout{&
%%Try "\string\usepackage[\string ?]{cmdtrack}"
%%to see information on using this package^^J&
%%[including how to turn off this "helpful" message].&
%%}
\endgroup
% \end{macrocode}
%
% \begin{macrocode}
\newcommand{\ShowPackageInfo}[1]{%
\begingroup \catcode`\?=3
\input{#1.\@pkgextension}%
\endgroup
}
% \end{macrocode}
%
% \begin{macrocode}
\let\@@yargdef\@yargdef
% \end{macrocode}
%
% Restore \cs{@yargdef} to normal at beginning of document, so that uses of
% \cs{newcommand} in \cs{maketitle} (e.g.\@) are ignored.
% \begin{macrocode}
\AtBeginDocument{\let\@yargdef\@@yargdef}
% \end{macrocode}
%
% \begin{macrocode}
\let\@hash@\relax
\def\@yargdef #1#2#3{%
\@tempcnta#3\relax \advance\@tempcnta\@ne \let\@hash@\relax
\edef\reserved@a{\ifx#2\tw@ [\@hash@ 1]\fi}%
\@tempcntb#2%
\@whilenum\@tempcntb<\@tempcnta\do{%
\edef\reserved@a{\reserved@a\@hash@\the\@tempcntb}%
\advance\@tempcntb\@ne
}%
\begingroup \escapechar=`\"\relax
\expandafter\log@cmd\csname\string#1\endcsname#1%
}
% \end{macrocode}
%
% The usual \cs{endinput} to ensure that random garbage at the end of
% the file doesn't get copied by \fn{docstrip}.
% \begin{macrocode}
\endinput
% \end{macrocode}
%
% \Finale