1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
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}
|
