diff options
author | Karl Berry <karl@freefriends.org> | 2006-01-09 00:44:40 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2006-01-09 00:44:40 +0000 |
commit | b4fc5f639874db951177ec539299d20908adb654 (patch) | |
tree | 52f08823ca58fffe3db6a9b075635038c567626c /Master/texmf-dist/doc/latex/diagnose/diagnose.tex | |
parent | dec3d98ebe442d7ea93efbaa8dd2e2be8149a467 (diff) |
doc 4
git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/diagnose/diagnose.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/diagnose/diagnose.tex | 166 |
1 files changed, 166 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/diagnose/diagnose.tex b/Master/texmf-dist/doc/latex/diagnose/diagnose.tex new file mode 100644 index 00000000000..ee3d3257084 --- /dev/null +++ b/Master/texmf-dist/doc/latex/diagnose/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} |