summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/diagnose/doc/diagnose.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/diagnose/doc/diagnose.tex')
-rw-r--r--macros/latex/contrib/diagnose/doc/diagnose.tex166
1 files changed, 166 insertions, 0 deletions
diff --git a/macros/latex/contrib/diagnose/doc/diagnose.tex b/macros/latex/contrib/diagnose/doc/diagnose.tex
new file mode 100644
index 0000000000..ee3d325708
--- /dev/null
+++ b/macros/latex/contrib/diagnose/doc/diagnose.tex
@@ -0,0 +1,166 @@
+\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}