Initial commit

1 files changed, 598 insertions, 0 deletions

diff --git a/macros/generic/occam/auditor.tex b/macros/generic/occam/auditor.tex
new file mode 100644
index 0000000000..20b40cf983
--- /dev/null
+++ b/macros/generic/occam/auditor.tex
@@ -0,0 +1,598 @@
+
+ %% 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...
+
+