diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-11 23:51:48 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-11 23:51:48 +0000 |
commit | 15d4fa4e32a7029e732aa5fe0f6ac5a4e2f28296 (patch) | |
tree | cc11a1db3f2435193427c30857822eed2b8508e1 | |
parent | 486c8ce4362f82f3a4131f3f30f28b018771b2c6 (diff) |
trunk/Master/texmf-dist/source/latex/cmdtrack
git-svn-id: svn://tug.org/texlive/trunk@193 c570f23f-e606-0410-a88d-b1316a301751
-rw-r--r-- | Master/texmf-dist/source/latex/cmdtrack/cmdtrack.dtx | 484 | ||||
-rw-r--r-- | Master/texmf-dist/source/latex/cmdtrack/cmdtrack.ins | 7 |
2 files changed, 491 insertions, 0 deletions
diff --git a/Master/texmf-dist/source/latex/cmdtrack/cmdtrack.dtx b/Master/texmf-dist/source/latex/cmdtrack/cmdtrack.dtx new file mode 100644 index 00000000000..47ea91a2d1b --- /dev/null +++ b/Master/texmf-dist/source/latex/cmdtrack/cmdtrack.dtx @@ -0,0 +1,484 @@ +%%% ==================================================================== +%%% @LaTeX-file{ +% filename = "cmdtrack.dtx", +%%% filename = "cmdtrack.sty", +%%% version = "1.05", +%%% date = "1999/07/22", +%%% time = "18:12:25 EDT", +%%% author = "Michael John Downes", +%%% email = "mjd@ams.org", +%%% copyright = "Copyright 1999 Michael John Downes. +%%% This program may be used, distributed, or +%%% even sold, without restrictions.", +% supported = "yes", +% 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.", +% checksum = "61105 484 1883 16399", +% docstring = "The checksum field above contains a CRC-16 +% checksum as the first value, followed by the +% equivalent of the standard UNIX wc (word +% count) utility output of lines, words, and +% characters. This is produced by Robert +% Solovay's checksum utility.", +%%% } +%%% ==================================================================== +% \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 +% +% \MakeShortVerb{\|} +% \newcommand{\qq}[1]{\textquotedblleft#1\/\textquotedblright} +% +% \maketitle +% \section{Introduction} +% +% 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}[1999/07/22 v1.05] +% \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 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} +% +% \CheckSum{403} +% \Finale diff --git a/Master/texmf-dist/source/latex/cmdtrack/cmdtrack.ins b/Master/texmf-dist/source/latex/cmdtrack/cmdtrack.ins new file mode 100644 index 00000000000..8420e37e87a --- /dev/null +++ b/Master/texmf-dist/source/latex/cmdtrack/cmdtrack.ins @@ -0,0 +1,7 @@ +\def\batchfile{cmdtrack.ins} +\input docstrip.tex +\preamble +\endpreamble +\keepsilent +\generateFile{cmdtrack.sty}{f}{\from{cmdtrack.dtx}{}} +\endinput |