path: root/macros/generic/occam/auditor.tex

 %% auditor.tex of 6-94 (alpha)
 %% "audits macro use"
 %% By  laurent siebenmann, lcs@topo.math.u-psud.fr (comments please!)
 %% Used mostly for Plain and amstex; LaTeX use not debugged.
 %% Documentation after endinput.
 %% Alpha posting on ftp ftp.math.u-psud.fr in pub/TeX/Occam.dir
 %% auditor.tex is part of the Occam system for macro management.
 %% But it can also be used alone.

 \ifx\undefined\auditortex\def\auditortex{}
 \else 
     \immediate\write16{}%
     \errmessage{%
   The auditor.tex macro \noexpand\Def already loaded\string!}%
 \EX@\endinput
 \fi

 \chardef\auditAt=\catcode`\@
 \catcode`\@=11

 %%temporarily suppress Plain's logging of allocations
 \let\auditorwlog@ld\wlog 
 \def\wlog#1{\relax} 

 \def\WrSc@{\immediate\write16}
 \def\WrOut@{\immediate\write\unusedout@}

     \WrSc@{}%
     \WrSc@{%
 *** The auditor.tex macro-auditing system}%
     \WrSc@{%
 *** is being installed for a test run of your typescript.}%
     \WrSc@{%
 *** Its report will appear after typesetting.}%
     \WrSc@{%
 *** See documentation in auditor.tex.}%
     \WrSc@{%
 *** Hit return to get audit.}%
    \WrSc@{%
 *** Hit \space x \space and return to typeset without audit.}% 
 \def\temp{\par}%
 \read16 to \YourChoice
 %\def\YourChoice{\par}%%%%%%%%%% comment out?
 \ifx\YourChoice\temp
   \def\Modify@Audit{}%
 \else 
   \def\Modify@Audit{\let\Def\def \let\gDef\gdef \let\Let\let 
   \def\gLet{\global\let}\let\The@Audit@\relax}%
     \WrSc@{%
  *** Auditor apparatus switched off\string.}%
 \fi
     \WrSc@{}%


 \newwrite \unusedout@
 \newtoks\temptoks@
 \newtoks\nibbletoks@
 \newtoks\resttoks@
 \newtoks\deftoks@
 \newtoks\mactoks@
 \newtoks\unusedtoks@
 \newtoks\AuditDepth

 \let\EX@\expandafter

 \def\Nibbl@#1#2\endNibbl@{\nibbletoks@{#1}\resttoks@{#2}}

 \def\gobble#1{}

 \def\WrDef@#1{\EX@
     \ifx\csname\string_%
           \string#1\string_\endcsname\@Used
     \else
         \EX@\global\EX@\let\csname\string_%
           \string#1\string_\endcsname\@Defed
         \edef\@tmp@{\global
            \noexpand\deftoks@{\the\deftoks@\noexpand#1}}%
         \@tmp@
     \fi
     }

 \def\WrDDef@#1{\EX@
     \ifx\csname\string_%
           \string#1\string_\endcsname\@Used
     \else
         \EX@\global\EX@\let\csname\string_%
           \string#1\string_\endcsname\@DDefed
         \edef\@tmp@{\global
            \noexpand\deftoks@{\the\deftoks@\noexpand#1}}%
         \@tmp@
     \fi
     }

 \def\@UsedMathSym{@UsedMathSym}
 \newtoks\Def@toks@
 \newtoks\Def@@toks@
 \newtoks\Font@toks@
 \newtoks\Mathchar@toks@
 \newtoks\MATHchar@toks@
 \newtoks\MATHchars@toks@

\def\Deff@{%
    \edef\@tmp@ {\@d@f\the\Def@toks@ {%\noexpand
           \global\let \EX@\noexpand\csname\string_%
           \EX@\string\the\nibbletoks@\string_\endcsname
           \noexpand\@Used
    \the\Def@@toks@ }}%
    \@tmp@
    \EX@\WrDef@\the\nibbletoks@
    }

\def\DDeff@{%
    \edef\@tmp@ {\@d@f\the\Def@toks@ {%\noexpand
           \global\let \EX@\noexpand\csname\string_%
           \EX@\string\the\nibbletoks@\string_\endcsname
           \noexpand\@Used
    \the\Def@@toks@ }}%
    \@tmp@
    \EX@\WrDDef@\the\nibbletoks@
    }

 \def\Def#1#{\Def@toks@{#1}%
     \Nibbl@#1\endNibbl@\let\@d@f\def
     \afterassignment\Deff@\Def@@toks@ 
     }

 \def\DDef#1#{\Def@toks@{#1}%
     \Nibbl@#1\endNibbl@\let\@d@f\def
     \afterassignment\DDeff@\Def@@toks@ 
     }

 \def\gDef#1#{\Def@toks@{#1}%
     \Nibbl@#1\endNibbl@\let\@d@f\gdef
     \afterassignment\Deff@\Def@@toks@ 
     }

  %% \Let \gLet require two *macros* following, without =
  %% Only then enhances \let
  \def\Let#1#2{%
    \EX@\Def\EX@#1\EX@{#2}%
    }
  \def\gLet#1#2{%
    \EX@\gDef\EX@#1\EX@{#2}%
    }

 \def\WrMATHchardef@{%
   \EX@\edef\the\MATHchar@toks@{%
     \noexpand\ifx
       \csname\string_\EX@\string\the\MATHchar@toks@\string_\endcsname
       \noexpand\@UsedMathSym
     \noexpand\else
        \global\MATHchars@toks@\noexpand\EX@{%
               \noexpand\the\MATHchars@toks@\the\MATHchar@toks@}%
        \global\let\csname\string_\EX@\string\the\MATHchar@toks@\string_\endcsname
              \noexpand\@UsedMathSym 
     \noexpand\fi
     \csname \EX@\string\the\MATHchar@toks@\string_\endcsname}
     %\EX@\show\the\MATHchar@toks@
    }

 \def\MATHchardef#1{\MATHchar@toks@{#1}%
     %\showthe\MATHchar@toks@
     \afterassignment\WrMATHchardef@
     \EX@\mathchardef\csname \string#1\string_\endcsname}

 \def\AfterMathchardef@{%
      \edef\@@temp@{%
         \noexpand\Def\the\Mathchar@toks@{%
            \csname \EX@\string\the\Mathchar@toks@\string_\endcsname}}
       %\show\@@temp@
       \@@temp@}

 \def\Mathchardef#1{\Mathchar@toks@{#1}%
     \afterassignment\AfterMathchardef@
     \EX@\mathchardef\csname \string#1\string_\endcsname}

 %%% \Newsymbol, \NEWsymbol for \newsymbol of amssym.def
  \def\Newsymbol#1#2#3#4#5{\let\next@\relax
    \ifnum#2=\@ne\let\next@\msafam@\else
    \ifnum#2=\tw@\let\next@\msbfam@\fi\fi
    \Mathchardef#1="#3\next@#4#5}

  \def\NEWsymbol#1#2#3#4#5{\let\next@\relax
    \ifnum#2=\@ne\let\next@\msafam@\else
    \ifnum#2=\tw@\let\next@\msbfam@\fi\fi
    \MATHchardef#1="#3\next@#4#5}

  \def\@F@nt@{\edef\@@temp@{%
         \noexpand\Def\the\Font@toks@{%
            \csname \EX@\string\the\Font@toks@\string_\endcsname}}%
       \@@temp@}

 \def\Font#1{\Font@toks@{#1}\afterassignment\@F@nt@
     \EX@\font\csname \string#1\string_\endcsname}

  \def\@FF@nt@{\edef\@@temp@{%
         \noexpand\DDef\the\Font@toks@{%
            \csname \EX@\string\the\Font@toks@\string_\endcsname}}%
       \@@temp@}

 \def\FFont#1{\Font@toks@{#1}\afterassignment\@FF@nt@
     \EX@\font\csname \string#1\string_\endcsname}

 \def\Loop@#1\Repeat@{%
    \def\Iterate@{#1\EX@\Iterate@\fi}%
    \Iterate@} 

  \bgroup\catcode`\%=12 
      \global\def\Pct@{ %% }\egroup

  \def\WriteToToks@{\edef\@tmp@{\global\noexpand
     \unusedtoks@{\the\unusedtoks@\the\nibbletoks@}}%
           \@tmp@}

  %\def\@Defed{@Defed}
  %\def\@Used{@Used}
  \def\@Used{\WrOut@{ \the\nibbletoks@}}%
  \def\@Defed{\WrOut@{ *\the\nibbletoks@}\WriteToToks@}%
  \def\@DDefed{\WrOut@{ **\the\nibbletoks@}\WriteToToks@}%
  \let\@Filler\relax
  \def\@Tail{@Tail}

   \def\List@M@cs{%
     \Loop@
       %\message{ x }
       \EX@\Nibbl@\the\deftoks@\@Tail\endNibbl@
       \deftoks@\resttoks@ %\showthe\resttoks@
       \edef\@Temp@{\EX@\noexpand\csname\string_%
           \EX@\string\the\nibbletoks@\string_\endcsname}%
       \EX@\let\EX@\@Temp\@Temp@ %
       %% \@Temp is x-equal and let-equal to 
       %% \@Defed  or  \@DDefed  or  \@Used  or \@Filler or @
      %\showthe\nibbletoks@
      %\show\@Temp@
      %\show\@Temp
     \EX@
     \ifx \the\nibbletoks@\@Tail
        %% exit if next token \@Tail
     \else
       \@Temp %% write appropriate stuff to file and log
       \Repeat@
     }

 \newtoks\hrct@


  {\catcode`\#=12\gdef\StringSharp{\string#}}

 \def\The@Audit@{%\show\patience
   \def\AuditSheet@{audit.lst}
   %%%
   \count255=\time\divide\count255 by 60\relax
   \edef\temp@{\the\count255}
   \multiply\count255 by -60\relax 
   \advance\count255 by \time
   \immediate\openout\unusedout@ \AuditSheet@
   \WrOut@{\Pct@ auditor.tex output, date 
   \the\day-\the\month-\the\year, 
   time \temp@\string:\the\count255.}%
   \WrOut@{}
   \edef\@temp@{\the\MATHchars@toks@}\def\empty{}%
   \ifx\@temp@\empty\else
     \WrOut@{\Pct@ Math characters defined via \noexpand\MATHchardef }
     \WrOut@{\Pct@ or \noexpand\NEWsymbol and really used were\string:}
     \WrOut@{\the\MATHchars@toks@}
     \WrOut@{\Pct@ Beware lack of wordwrap\string!}
     \WrOut@{}
   \fi
   \WrOut@{\Pct@ Macros (if any) defined by \string\Def, \string\Let, etc.}%
   \WrOut@{\Pct@ are listed in order defined\string:}
   \WrOut@{\Pct@ *Unused* macros among these are marked by * or \StringSharp.}%
   \WrOut@{\Pct@ And **, ***, etc. indicate nesting (hence delayed action).}%
   \WrSc@{}%
   \WrOut@{}%
   \List@M@cs
   %\showthe\unusedtoks@
   %\showthe\deftoks@
   \def\empty{}%   
   \edef\@tmp@{\the\unusedtoks@}%
   \ifx\@tmp@\empty
      \EX@\def\EX@\@tmp@\EX@{\the\deftoks@}%
      \ifx\@tmp@\empty
        \WrSc@{*** No macros have been defined via \string\Def, 
               \string\Let, etc.}%
      \else
      \WrSc@{*** All macros defined via \string\Def, 
               \string\Let, etc. have been used.}%
      \fi
    \else
      \WrSc@{*** The following macros defined via \string\Def, 
               \string\Let, etc. have not been used\string;}%
      \WrSc@{%
           ***  --- you can probably delete their definitions\string:}%
      \WrSc@{*** }%
      \WrSc@{***** \the\unusedtoks@}%
   \fi
   \edef\@tmp@{\the\MATHchars@toks@}%
   \ifx\@tmp@\empty\else
      \WrSc@{ }%
      \WrSc@{*** The following math chars defined by \noexpand\MATHchardef}%
      \WrSc@{*** or \noexpand\NEWsymbol are really used\string:}%
      \WrSc@{***** \the\MATHchars@toks@}%
   \fi
   \WrSc@{}%
   \WrSc@{*** See the file \string"\AuditSheet@\string" for details.}%
   \WrSc@{*** See the DefStrip utility for cleanup.}%
   \WrOut@{}
   \WrOut@{\the\AuditDepth\noexpand\ITERATIONCOUNTER}
   \WrOut@{\Pct@ PLEASE iterate  ***defstrip  macro of QUEDM }
   \WrOut@{\Pct@ until asterisks disappear from iteration counter line.}
   \WrOut@{\Pct@ Name successive output files output1, output2, ...}
   }

  \ifx\undefined\@@end
   \let\audprim@end@\end
   \def\end{\The@Audit@\audprim@end@}
 \else  %%% LaTeX
   \let\audprim@end@\@@end
   \def\@@end{\The@Audit@\audprim@end@}
 \fi

 \Modify@Audit

 \let\wlog\auditorwlog@ld
 \catcode`\@=\auditAt

 %\let\DDef\Def

 \endinput %% comment out for tests

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% end code
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% begin tests

 \input amssym.def
 \input amssym.occ

$\digamma\digamma\varkappa$

\Font\cmr cmr10 scaled 1500
%\cmr

\end

 %\catcode`\@=11


 %\documentstyle{article} %% LaTeX only
 %\begin{document} %% LaTeX only
 %\let\Def\def
 %\let\Let\let

 \Def\Rm#1{\mathop{\fam0#1}}

 \Def \End {\Rm {End}}
 \Def \Hom {\Rm {Hom}}
 \Def \ind {\Rm {ind}}
 \Def \Re {\Rm {Re}}
 \Def \Tr {\Rm {Tr}}
 \Def \rk {\Rm {rk}}
 \Def \rg {\Rm {rg}}
 \Def \Td {\Rm{Td}}
 \Def \ch {\Rm{ch}}
 \Def \T{\Rm{T}}
 \Def \R{\Rm{R}}
 \Def \e{\Rm{e}}
 \Def \odd {\Rm{odd}}
 \Def \even {\Rm{even}}
 \Def \Ker {\Rm{Ker}}
 \Def \id {\Rm{id}}
 \Def \Pf {\Rm{Pf}}

 \gDef\filler{filler}
 \gLet\Filler\filler

 %\Filler

 \Font\myfont=cmr10 at 11.5pt 
 %\myfont 
 
  $\End 
 %\Hom 
 \ind 
 \Re 
 \Tr 
 \rk 
 \rg 
 \Td 
 \ch 
 \T
 \R
 \e
 %\odd 
 %\even 
 \Ker 
 \id 
 \Pf  $

 \end{document}

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% end tests
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% begin doc


DOCUMENTATION FOR auditor.tex.


   Warnings : These macros are not bulletproof. I believe no such
macros could be bulletproof. But in practice that should be of
no importance;  hopefully, any significant annoyances will be
routinely reported and remedied.  Use of this  alpha version
with an imbricated format like LaTeX is probably for hardened
texperts only.  Plain and AmSTeX seem to respond well.

   INSTRUCTIONS.

  Suppose you have a macro file x.sty used for typesetting the
typescript  x.tex.  The aim is to find out, quickly and easily,
which of the macro definitions in x.sty are necessary to typeset
x.tex.

 1)  Modify a *copy* of  x.sty  to  x-occ.sty  by altering
definitions as follows:

      (a) replace \def by \Def for definitions of macros you suspect
          might be unused in x.tex.  Similarly use \gDef in place
          of \gdef or \global\def.

      (b) similarly replace \mathchardef  by \Mathchardef, and so forth
      as indicated in the list of currently possible substitutions
      indicated in occam.spc.

Provisional Warnings:
 --- Do not modify \def's or \let's within other definitions.
This would be pointless and perhaps dangerous. Be ready to
revert to \def or \let if trouble ensues.
 --- Avoid "\outer" and "\long" macros; also \alloc@

      (c)  Place the lines 

   %%%   auditor.tex audits use of macros in a typescript.
   \input auditor.tex   %% Keep this file available to TeX!

at the head of x-occ.sty. (Watch the order!)

 2)  Modify  x.tex temporarily replacing 

     \input x.sty      by      \input x-occ.sty   

in the header. Typeset as usual.  The audit should now proceed
with an explanatory dialog.

 3)  If there is trouble in step 2), repeat it choosing (by
dialog) to compose *without* an audit.  There should be no
change from the original behavior of x.tex. Correct any
misbehavior --- probably arising from a malformation in
x-occ.sty.  Sometimes, here and there in  x-occ.sty, one has to
change  \Def  back to \def etc.

 4)  Delete the unused definitions in another copy of x.sty, say
x-min.sty. The list in the "audit.lst" output file is designed to
make this easy, in fact so easy that a utility called "defstrip" can
do the job automatically. Then replace  x-occ.sty   by  x-min.sty in
the header of x.tex.  Typeset x.tex and check a proof copy.

 5)  You can now send  x.tex and  x-min.sty to a colleague or
publisher, without burdening him/her with useless macros present in
x.sty.

     


IMPROVEMENTS CURRENT AND FUTURE  
 A)   In all, the list of prepared macros is currently (July
1994):

   \Def, \Let, \gDef, \gLet, \Font, \Mathchardef, \Newsymbol 

Unless the contrary is indicated, each is to be used in analogy
with \Def replacing in  x.sty  a corresponding uncapitalized TeX
primitive.

     [Exception: \newsymbol (from amssym.def) is *not*
primitive; it is used copiously for declaration of symbols from
the AmS math fonts msam and msbm, as in amssym.tex.]

      When the file amssym.tex is \input, huge numbers of math
characters are defined via \newsymbol but only few are used.  In
this case it is appropriate to use variants \MATHchardef,
\NEWsymbol. which signal math characters only if they are used
--- and *not* if they are unused. For this, try temporarily
replacing

   \input amssym.tex 

in  x-occ.sty (after \input auditor.tex please)  by 

   \input amssym.occ

where  amssym.occ  is obtained from  amssym.tex  by replacing
\newsymbol by \NEWsymbol; then you get a list of the symbols really
needed in x.tex.

      In using \Let and \gLet, avoid macros with parameters and
note that the condition that the second argument be a macro is
often not satisfied.  Do not use = in the syntax.

      \Let, \gLet, and \Font tend to be troublesome; while
\Mathchardef, \MATHchardef, \Newsymbol, \NEWsymbolseem tend to
be troublefree.

     The usefullness of the above list can be stretched by the
user. For example, before \Font was introduced

\font\myfont=cmr10 scaled 11.5pt

would have been replaced by

 \font\myfont@=cmr10 at 11.5pt  \Def\myfont{\myfont@}

to report use of \myfont.

     In many formats, user definitions are made via macros not
available in Plain TeX; for example,   \define  and \redefine in
AmSTeX.  In practice, they can usually be replaced by \Def for
the audit.  But the programmer may want to invent new macros,
say \Define and \Redefine for AmSTeX.
  (B)  In case x.sty is of permanent interest, it is a good idea
to begin to use  x-occ.sty instead of  x.sty  after commenting
out the line \input auditor.tex and replacing it by something
like

  %% Audit.tex apparatus
  \let\Def\def \let\gDef\gdef \let\Let\let
  \let\Font\font \def\gLet{\global\let}
  \let\Mathchardef\mathchardef %% extend as necessary
  % \input auditor.tex %% comment out to suppress audit function

This will make steps (1) to (4) superfluous for your next
typescript y.tex.

  (C)  DefStrip automates the generation of x-min.sty.
(auditor.tex plus DefStrip make up the "Occam" utility.)
Its starting materials are "x-occ.sty"  plus the "list audit.lst"
of unused macros provided by auditor.tex.  This depends on a
special arrangement of x-occ.sty described in occam.spc.

        Ultimately, an auxiliary ".tex" program "defstrip.tex"
will rewrite  x-occ.sty omitting the inused definitions.   This
auxiliary program resembles the "docstrip" utility of LaTeX
fame.

        At the present time defstrip.tex is unavailable. But there
exists a QUEDM script called Auditor-QUEDM-Macros;  QUEDM is a
editor with convenient "macro" (=composite command) capabilities
that is available on Macintosh computers at prices as low as $60
The instructions for Auditor-QUEDM-Macros are found in
defstrip.hlp.


  *** How  "auditor.tex"  functions or fails to function.

     "auditor.tex" prefixes a reporting device to the expansion
of macros defined by \Def; this device reports the use of the
macro by defining a tell-tale auxilliary macro that is then
polled after typesetting. But it may cause strange behavior or
even stop TeX.

    As has been mentioned auditor.tex is not bullet-proof. Any
change whatever in the expansion of a macro can in principle
alter its behavior.  For example TeX can use \ifx and many other
means to examine the expansion of a macro; it can detect any
tampering with definitions.  


  *** The "watchman" mechanism. 
 
     This mechanism is capable of deleting any collection of
lines of a macro file in response to the non-use of a single
macro called the "watchman". This "watchman" may be a macro that
is specially defined for the purpose. The mechanism is
definitely only for macro files carefully formatted for Occam.
This mechanism is more powerful but more cumbersome than that
for \Def etc.  It is still to be implemented.


CAVEAT LaTeX :    LaTeX environments tend to define their user
macros locally; indeed their definitions are not set up while
the macro file x.sty is being read but when the environment is
entered. Thus the modus operandi indicated above is suspect.
However, normally, the meanings assigned upon entering the
environment are stored in macros whose name involves @ ; these
are possibly the macros to spy on with \Def etc. Alternatively,
the "watchman" mechanism may prove effective. The cleanup based
on audit.lst is then still a delicate matter requiring texpert
attention. Further, LaTeX's fragility must be attended to...