doc 4

git-svn-id: svn://tug.org/texlive/trunk@80 c570f23f-e606-0410-a88d-b1316a301751

4 files changed, 379 insertions, 0 deletions

diff --git a/Master/texmf-dist/doc/latex/diagnose/README b/Master/texmf-dist/doc/latex/diagnose/README
new file mode 100644
index 00000000000..9bc9cfaab8d
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/diagnose/README
@@ -0,0 +1,25 @@
+Package name:		diagnose.sty
+Package authors:	Oliver Corff
+Version/Release:	version 0.2
+
+Features:
+
+This tool, diagnose.sty, is thought useful for package authors who
+want to facilitate the successful distribution of their packages.
+It helps the user (and the system administrator) to see what has to
+be done *before* a new package is installed.
+
+diagnose.sty provides simple high-level tools for checking
+the existence of files and tokens. Software action can be
+triggered, messages can appear in log files and documents.
+
+Compiling the example mls-diag.tex and reading its source text will
+show the idea behind this little utility.
+
+Installation:
+
+Unpack this archive and copy diagnose.sty to some place where
+your LaTeX installation can find it. Rehash the directory database.
+That's it!
+
+OC, April 2001
diff --git a/Master/texmf-dist/doc/latex/diagnose/diagnose.pdf b/Master/texmf-dist/doc/latex/diagnose/diagnose.pdf
new file mode 100644
index 00000000000..ad11f6133bc
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/diagnose/diagnose.pdf
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}
diff --git a/Master/texmf-dist/doc/latex/diagnose/mls-diag.tex b/Master/texmf-dist/doc/latex/diagnose/mls-diag.tex
new file mode 100644
index 00000000000..e40c27f6cae
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/diagnose/mls-diag.tex
@@ -0,0 +1,188 @@
+\documentclass[a4paper,11pt]{article}
+\usepackage{diagnose}
+
+\title{Mon\TeX\ Diagnostics:\\
+	System Compatibility Report}
+\author{Oliver Corff}
+
+\begin{document}
+\maketitle
+\begin{abstract}
+	Running \LaTeXe\ on this article will give information
+	on the status of system software necessary for exploiting
+	advanced features of Mon\TeX: RL line orientation, vertical
+	text, extended Cyrillic characters for Kazakh and the
+	text-mode gamma.
+\end{abstract}
+
+\section{Introduction}
+
+Mon\TeX\ relies on numerous functions supplied by the existing
+\LaTeXe\ installation for offering advanced services. Before installing
+Mon\TeX\ it might be interesting to find out which support is offered
+by the system and which additional packages should be supplied in order
+to raise Mon\TeX\ to its complete functionality.
+
+This document will tell you which functionality is really available on
+your system and
+what you should do in case the desired support is missing. Whenever the
+text informs you that something from CTAN (the Comprehensive TeX Archive
+Network) should be installed then you have the choice to obtain the
+required software from CTAN via the Internet or from a CD-ROM with the 
+contents of the CTAN site. In short, this will usually be the same source
+from which you obtained Mon\TeX.
+
+
+\section{RL Line Orientation\label{RLSupport}}
+
+If you want to be able to print complete paragraphs of Uighur Mongolian 
+texts, and not limit yourself to individual words and phrases, then you
+will most certainly require the correct writing direction for Uighur 
+Mongolian which starts at the right end of line rather than the left end,
+as supplied by Implementation Levels III and IV of Mon\TeX.
+Apart from its vertical orientation, Uighur Mongolian is a RL writing
+much like Arab and Hebrew. The RL mechanism is provided by modern
+\LaTeXe\ installations.
+
+\TokenDiagnostics%
+	{\TeXXeTstate}				% Token tested for
+	{RLSupportAvailable}			% Associated counter
+	{RL Support Available!}			% Yes message
+	{RL Support Not Available!}		% No! message
+
+\textbf{Your system status}:
+\ifnum\theRLSupportAvailable=1
+	Your system is up to date and provides support for RL writings.
+	No further action is required.
+\else
+	During this \LaTeXe\ run, your system did not reveal that it is
+	capable of typesetting RL writings correctly.
+	
+	\textbf{Action required}:
+	Please make sure
+	\marginpar{\Huge!!!}
+	you started \texttt{elatex} instead of \texttt{latex} for calling
+	e-\LaTeXe. If this message persists then you should install a
+	recent \TeX\ distribution from CTAN.
+\fi
+
+
+\section{Vertical Text\label{VerticalText}}
+
+If you want to mix horizontal and vertical text on one page your
+system needs PostScript support. This implies that your \TeX\ 
+installation can handle insertions of PostScript commands in
+documents (this is done automatically without your interaction);
+it does not imply that you can print the results on your printer
+if your printing equipment is not PostScript-compatible.
+
+\PackageDiagnostics%
+	{rotating.sty}				% Package tested for
+	{PostScriptAvailable}			% Associated counter
+	{PostScript Support Available!}		% Yes message
+	{PostScript Support Not Available!}	% No! message
+	
+\textbf{Your system status}:
+\ifnum\thePostScriptAvailable=1
+	Your \TeX\ installation can handle vertical text; if your
+	system does not display or print vertical text properly
+	then you should check whether you do have a PostScript
+	printer or interpreter like GhostScript and GhostView.
+\else
+	Your \TeX\ installation cannot handle vertical text.
+
+	\textbf{Action required}:
+	You should either install a \TeX\ system with pre-configured
+	\marginpar{\Huge!!!}
+	PostScript support or should install PostScript support
+	from CTAN.
+\fi
+%
+
+\section{Uighur Mongolian Text Pages}
+
+\textbf{Your system status}:
+\ifnum\theRLSupportAvailable=0
+	Since your system does not offer RL support (see above)
+	%\ref{RLSupport})
+	this section is meaningless and should be skipped.
+\else
+	If you want to put Uighur text in vertical pages which
+	show the proper orientation without physically rotating
+	the paper they are printed on (like in books with a
+	mixture of Uighur Mongolian and Modern Mongolian articles)
+	you must make sure that your installation has so-called
+	landscape orientation support.
+
+	\PackageDiagnostics%
+		{lscape.sty}				% Package tested for
+		{LandscapeAvailable}			% Associated counter
+		{Mongol Bicig Page Support Available!}	% Yes message
+		{Mongol Bicig Page Support Not Available!}% No! message
+
+	\ifnum\theLandscapeAvailable=1
+		Your system has landscape orientation support and
+		does not require any action.
+	\else
+
+		\textbf{Action required}:
+		You should install landscape orientation support
+		(usually this is done together with support for
+		vertical text material, see above \ref{VerticalText}).
+	\fi
+\fi
+
+
+\section{Extended Cyrillic Support}
+
+Beyond the basic Cyrillic support which is provided by Mon\TeX\ for
+writing Modern Xalx Mongolian, Buryat and last but not least, Russian,
+Kazakh requires additional Cyrillic characters which are not supplied
+by Mon\TeX.
+
+\PackageDiagnostics%
+	{x2enc.def}				% Package tested for
+	{LHCyrillicAvailable}			% Associated counter
+	{Cyrillic Support for Kazakh available!}% Yes message
+	{Cyrillic Support for Kazakh Not Available!}% No! message
+
+\textbf{Your system status}:
+\ifnum\theLHCyrillicAvailable=1
+	Since your installation offers the full range of extended
+	Cyrillic characters, it is possible to write Kazakh on your 
+	system. No further measures are required.
+\else
+	Your installation does not offer the extended Cyrillic character
+	set necessary for writing Kazakh. You should install the LH
+	Cyrillic package from CTAN. Even without this support, your
+	Mon\TeX\ package as such is fully functional.
+\fi
+
+\section{Gamma Support}
+
+The Greek gamma $\gamma$ is used in transliterations for Uighur 
+Mongolian Script. Without support of Modern Greek fonts, only
+the slim, italic $\gamma$ used in mathematics is available.
+If you want to match its typeface with all Latin and Cyrillic
+letters used in Mon\TeX\ then you should make sure the Modern
+Greek fonts are installed.
+%
+\PackageDiagnostics%
+	{lgrenc.def}				% Package tested for
+	{GreekAvailable}			% Associated counter
+	{Greek Support for Gammas available!}% Yes message
+	{Greek Support for Gammas Not Available!}% No! message
+
+\textbf{Your system status}:
+\ifnum\theGreekAvailable=1
+	On this system, the Modern Greek fonts \textit{are} installed.
+	There is no further action necessary.
+\else
+	Your system does not feature the Modern Greek fonts.
+
+	\textbf{Action required}:
+	If you use transliterations extensively and need a matching
+	typeface for the $\gamma$ then you should get the Modern
+	Greek fonts from CTAN and install them now.
+\fi
+\end{document}