\documentclass{ltxdoc} \usepackage{diagnose} \title{Installation Diagnostics with\\\texttt{diagnose.sty} version 0.2} \author{Oliver Corff\\\texttt{corff@zedat.fu-berlin.de}} \date{April 10th, 2001} \begin{document} \maketitle \tableofcontents \section{Introduction} Large \LaTeXe\ packages with extensive functionality are ideally written with the support offered by the \LaTeXe\ installation in mind as it does not make sense to reinvent the wheel or copy code from other packages. If a package makes use of other packages in the system there should be a means to test for the presence of the required package, or a required token. Depending on the result of this test, several situations are possible. Either the calling package fails completely, or fails to provide the intended service in its full scope, or has to check for some alternative. In any case, an informative message should be written into the log file and perhaps also into the text document. \TeX\ and \LaTeXe\ provide basic functionality for testing the existence of files and tokens; this package goes a step further and provides mechanisms for informing the software and the user about a detected condition. Besides providing a simple mechanism for repeated references to the existence of a file or token, the other important application is for checking whether a complex application can be used immediately after installing or whether it requires additional software to be installed. For this purpose, \LaTeX\ packages can now be accompanied by a simple text document which, when compiled, checks the user's environment and makes suggestions about missing software, if necessary. An example of this idea is given in the file \texttt{mls-diag.tex}. \section{The \texttt{diagnose} Package} The \texttt{diagnose} package is included with the usual \begin{verbatim} \usepackage{diagnose} \end{verbatim} statement. There are no options at present. The four commands offered are: \begin{enumerate} \item \texttt{\char92 PackageDiagnostics} \item \texttt{\char92 TokenDiagnostics} \item \texttt{\char92 TextMessageYes} \item \texttt{\char92 TextMessageNo} \end{enumerate} \subsection{\texttt{\char92 PackageDiagnostics}} \begin{verbatim} \PackageDiagnostics{} % Tested package {} % Associated counter {} % message if file available {} % message if file not available \end{verbatim} This command verifies whether a file is available within the \TeX\ directory structure. It is based on the \LaTeXe\ command \texttt{\char92 IfFileExists\{\}} and offers the possibility to create a counter which is associated with the existence of the requested file. The counter can then be used throughout the software without additional calls of \texttt{\char92 IfFileExists\{\}}. Two message texts can be given; one will be printed if the file exists, the other will be printed if the file is absent. By default the message texts appear in the log file and the terminal output of the running caller program; additionally it is possible to have the messages appear in the output text of the document. \subsection{\texttt{\char92 TokenDiagnostics}} \begin{verbatim} \TokenDiagnostics{} % Tested token {} % Associated counter {} % message if token available {} % message if token not available \end{verbatim} This command verifies whether a token (a command sequence, etc.) is known to the system. Like \texttt{\char92 PackageDiagnostics} it accepts an associated counter and two message texts as arguments. \subsection{\texttt{\char92 TextMessageYes}} By default, messages generated by the two diagnostics commands appear only in terminal output and log files. If the messages shall also be displayed in the output text then the command \begin{verbatim} \TextMessageYes \end{verbatim} is to be used. It is not followed by any argument. By default, message texts do not appear in the output text, only in log files and terminal output. \subsection{\texttt{\char92 TextMessageNo}} If output of diagnostics messages to the main text had been enabled before, it can be disabled with the command \begin{verbatim} \TextMessageNo \end{verbatim} which happens to be the default of the diagnostics package. \section{Examples} Two examples are given here. First the usage of the package diagnostics command is shown, and, in a separate file, the reader is invited to compile the accompanying document \texttt{mls-diag.tex} which shows a real-life application of \texttt{diagnose.sty}. \begin{verbatim} \PackageDiagnostics{rotating.sty} % Tested package {RotatingAvailable} % Associated counter {Vertical text possible!} % message if file available {rotating.sty not found, no vertical text!} % message if not \ifnum\theRotatingAvailable=1 You can use vertical text in your documents. No further measure is required. \else Without the \texttt{rotating.sty} package vertical text cannot be typeset. If you need this option, then access CTAN and install \texttt{rotating.sty} on your system. Make sure you can process PostScript output. \fi \end{verbatim} The actual output of this command sequence will depend on the presence of \texttt{rotating.sty} on the system where this source file is compiled: \begin{quote} \PackageDiagnostics{rotating.sty} % Tested package {RotatingAvailable} % Associated counter {Vertical text possible!} % message if file available {rotating.sty not found, no vertical text!} % message if not \ifnum\theRotatingAvailable=1 You can use vertical text in your documents. No further measure is required. \else Without the \texttt{rotating.sty} package vertical text cannot be typeset. If you need this option, then access CTAN and install \texttt{rotating.sty} on your system. Make sure you can process PostScript output. \fi \end{quote} You can also see that the log file and the terminal output contain the appropriate message. \section{Legal Status} This software is placed under the GPL. Usual disclaimers apply. As this software tool is still under development, suggestions on how to improve the usability and versatility of this package are highly appreciated. \end{document}