%Copyright (C) 2000  G. Lamprecht, W. Lotz, R. Weibezahn; IWD, Bremen University
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%
% LaTeX version dependent stuff:
%
%--------------------------------------
%
% LaTeX2e
%
\documentclass{article}
\newcommand{\It}[1]{\textit{#1}}
\newcommand{\BrL}{\textnormal{\{}}
\newcommand{\BrR}{\textnormal{\}}}
%
%--------------------------------------
%
% LaTeX2.09
%
%\documentstyle{article}
%\newcommand{\It}[1]{{\em#1\/}}
%\newcommand{\BrL}{{\tt\{}}
%\newcommand{\BrR}{{\tt\}}}
%
%--------------------------------------
%
% end of LaTeX version dependent stuff
%
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\textheight 245mm \topmargin 0mm \headheight 0mm \headsep 0mm \voffset -10mm   \hoffset -10mm
\textwidth 170mm  \oddsidemargin 10mm

\renewcommand{\sloppy}{\tolerance 9999}
\sloppy\hbadness9999

\parindent 0mm   \parskip 1 ex plus 3ex minus 0.5ex
\topsep 0.1ex \partopsep 0.5ex 

\newcommand{\MajorVersion}{8}           %%%%%%  xtem major version (= version)
\newcommand{\MinorVersion}{8.00}        %%%%%%  xtem minor version (= release) xtem-Version
\newcommand{\DateEngl}    {December 2000}   %%%%%%  date
\newcommand{\offen}{\rule{1em}{2ex}}
\newcommand{\Copyright}{Copyright (C) 2000  G. Lamprecht, W. Lotz, R. Weibezahn; IWD, Bremen University}
\newcommand{\bsl}{\mbox{$\backslash$}}
\newcommand{\xtem}{{\tt xtem}}
\newcommand{\xteminstall}{{\tt xteminstall}}
\newcommand{\xtemtexmenu}{{\tt xtem{\UL}texmenu}}
\newcommand{\iwdinternet}{{\tt iwd.uni-bremen.de}}
\newcommand{\xtememail}{{\tt weibezahn@\iwdinternet}}
\newcommand{\majordomo}{{\tt majordomo@\iwdinternet}}
\newcommand{\xtemhttp}{{\tt http://www.\iwdinternet/xtem/xtem{\UL}texmenu.html}}
\newcommand{\ftpiwdpub}{{\tt ftp://ftp.\iwdinternet/pub/}}
\newcommand{\ftpiwdtex}{{\tt \ftpiwdpub tex/}}
\newcommand{\ftpiwdxtem}{{\tt \ftpiwdtex xtem/}}
\newcommand{\ftpiwdtcl}{{\tt \ftpiwdpub tcl/}}
\newcommand{\ftpOrigTclTk}{{\tt ftp://ftp.scriptics.com/pub/tcl/}}
\newcommand{\instimpmes}{if installation cannot be done because of missing access permission,
                        a message with the commands to be executed is produced}
\newcommand{\hoehe}{\rule{0mm}{2.1ex}}
\newcommand{\Institution}{IWD}
\newcommand{\Blank}{blank-character}
\newcommand{\button}[1]{``#1''}
\newcommand{\Button}[1]{button \button{#1}}
\newcommand{\UL}{\protect\rule{0.4em}{0.1ex}}
\newcommand{\vvv}{\It{v.vv}}
\newcommand{\nnn}{\It{nnn}}
\newcommand{\nnnch}[1]{\It{nnn}=#1 characters}
\newcommand{\param}[1]{#1 parameter}
\newcommand{\novar}{--}
\newcommand{\Empty}{Empty (blank(s))}
\newcommand{\InstProc}{installation procedure}
\newcommand{\lang}{\It{language}}
\newcommand{\crit}{criterion}
\newcommand{\fnam}{\It{filename}}
\newcommand{\link}{\(\rightarrow\)}
\newcommand{\einr}{\hspace*{2em}}
\newcommand{\mkAbschnitt}[1]{\vspace*{-2ex}\subsubsection*{\tt #1}\vspace*{-2ex}}
\newcommand{\tvspace}{\rule{.1ex}{.5ex}\rule{1ex}{.1ex}\rule{.1ex}{.5ex}}
\newcommand{\excch}{{\tt , {\UL} \BrL{} \BrR{} \tvspace{} {\tt "}}}
\newcommand{\vstfile}[4]{\pagebreak[#1]\subsubsection{{\tt#2}\,---\,#3}
                        File {\tt INSTPATH/xtem/locals{\UL}\It{language}/#2}~: 
                        #4;\\ structure (for examples look at file {\tt\XtllP.LRW/#2}):}
\newcommand{\FLine}[1]{{\bf 1st line:} first non-blank character: field separator for this file (any character 
                        with the exception of one of the characters: `\excch')#1\\}
\newcommand{\FALines}{\FLine{.\\{\bf All other lines:}}}
\newcommand{\DefLine}[1]{\par The values from #1 line are taken as default values.}
\newcommand{\LATeX}{(L\hspace*{-.35em}\raisebox{0.45ex}{{\sc a}})\TeX}
\newcommand{\vn}{10em}\newcommand{\vv}{35.5em}
\newcommand{\XtP}{{\tt INSTPATH/xtem}}
\newcommand{\XtllP}{{\tt\XtP/locals{\UL}\lang}}
\newcommand{\ButSup}[1]{The button in the \xtem{} menu corresponding to this file can be
                suppressed, look at variable {\tt #1} in file {\tt install.vst} (\sRef{install.vst}).}
\newcommand{\Ref}[1]{section~\ref{#1}}  \newcommand{\Refs}[1]{sections~\ref{#1}}
\newcommand{\sRef}[1]{see \Ref{#1}}     \newcommand{\sRefs}[1]{see \Refs{#1}}
\newenvironment{vstfmt}%
        {\hspace*{0.7em}\begin{tabular}{llp{31em}}}%
        {\end{tabular}}
\newenvironment{mlist}%
        {\begin{list}{$\bullet$}{\topsep0.1ex\parskip0.5ex\partopsep1ex\itemsep0.1ex
                        \parsep0.1ex\leftmargin 2.5em\rightmargin 1em}}%
        {\end{list}}
\newcommand{\Item}[1]{\pagebreak[1]\item[{\bf#1}]}
\newcommand{\sameaslastfootnote}{\addtocounter{footnote}{-1}\footnotemark}
\newcommand{\mkcommand}[1]{{\tt mkcommand#1}}
\newcommand{\TL}{\\}
\newcommand{\quickdirty}{Quick\&{}Dirty}

\title{\xtem\,---\,\TeX-Menu for X Window System\\ Installation \& Maintenance Guide\\
        {\normalsize Release \MinorVersion} \\ {\normalsize \Copyright} }
\author{G. Lamprecht,
        W. Lotz, 
        R. Weibezahn\thanks{e-mail: {\xtememail},\qquad WWW:\quad{\xtemhttp}}
     \\ \Institution, Universit\"at Bremen, Postfach 330 440, D28334 Bremen, Germany}
\date{\DateEngl}



\begin{document}
 
\maketitle 

\tableofcontents %\newpage



\section{How to Read this Manual}\label{HowToRead}

This manual seems to be rather long, but normally you will only need some sections.

Normally you will just move file {\tt xtem{\UL}texmenu.\vvv.tar.gz} to the directory in which you want to
install \xtem{} (e.g.\ {}{\tt/usr/local/lib/tex}), unzip and untar the file (pay attention to keep the symbolic links
in file {\tt xtem{\UL}texmenu.\vvv.tar.gz}, e.g.\ {}by calling tar with the -h option),
{\tt cd xtem-\vvv}, edit file \xteminstall{} and then call \xteminstall{} (click at \Button{install xtem}
in the menu coming up, \sRef{Installation}).
For this installation run you should have write permission for the \ldots{\tt/man/} directory and
for the \ldots{\tt/bin/} directory (otherwise messages are given to you with the Unix commands to install
the man page and the \xtem{} shell script etc. You can run \xteminstall{} more than once without any problems!
After this you can call \xtem{} and see what happens (the \xtem{} menu has to come up);
the next step will be to click at \Button{exec mode} and check the different versions of \mkcommand{}.

Extremely spoken we can say: first you have to look only at sections \Refs{Installation} and~\ref{mkcommand}; all 
other sections perhaps you never will have to look at!




\section{Getting \xtem}\label{GettingXtem}

You may get xtem  directly from the authors (user: anonymous, password: RFC-conform e-mail address):

\hfuzz 200pt
{\hfuzz 10pt
\begin{tabular}{ll}
 \tt\ftpiwdxtem xtem{\UL}texmenu.\vvv.tar.gz & \vvv\,=\,{}release,\,e.g.\ {}{\tt\MinorVersion}\\
 \tt\ftpiwdxtem xtem{\UL}texmenu{\UL}Patch{\UL}\It{yymmdd} & patches (\It{yymmdd}=date)\\
 \tt\ftpiwdxtem xtem{\UL}texmenu{\UL}\It{v}eng.ps.gz    & (English description)\\
 \tt\ftpiwdxtem xtem{\UL}texmenu{\UL}\It{v}ger.ps.gz    & (German description)\\
                                                & \It{v}\,=\,{}version,\,e.g.\ {}{\tt\MajorVersion}\\
 \xtemhttp\rule{0mm}{2.5ex}
\end{tabular}
}


Program \xtem{} can be used and copied under the conditions of the GNU GENERAL PUBLIC LICENSE
(added as file COPYING), the Copyright must not be deleted or modified.

{\bf In no event shall the \Institution{} be liable to any party for direct, indirect, special, incidental,
or consequential damages arising out of the use of this software and its documentation, even if
the \Institution{} has been advised of the possibility of such damage.

The \Institution{} specifically disclaims any warranties, including, but not limited to, the implied warranties
of merchantability and fitness for a particular purpose. The software provided hereunder is on an ``as is'' basis,
and the \Institution{} has no obligation to provide maintenance, support, updates, enhancements, or modifications.}

\bigskip
For a successful installation you need:
\begin{mlist}
\item   Unix
\item   C compiler (e.g.\ {}GNU {\tt gcc} compiler)
\item   Tcl, Tk (for ftp servers etc.\ {}see file {\tt README} or the \xtem~home~page mentioned above).
\item   X11      R4, R5 or R6
\item   3-button mouse (2-button mouse will also work)
\end{mlist}



This version of \xtem{} runs with different Tcl versions:
\begin{mlist}
\item   Tcl version 7.6, 8.0 (not tested) or 8.1\\
        (if you have installed another Tcl $\geq$\,7.4, you can look at our ftp server for more \xtem{} versions,
        look also at file {\tt README.Tcl-version}),
        with Tcl $>$8.1 this version of \xtem{} will produce a warning (you can set variable {\tt noWarnTcl}
        (\sRef{install.vst}) in order to suppress this warning).
\item   corresponding version of Tk
\end{mlist}

The installation of Tcl, Tk was without problems (INTEL x86 running Linux 2.0.36)
by means of the {\tt Makefile} and {\tt Configure}, using GNU {\tt gcc} compiler.

The executable programs produced this way are:
{\tt tclsh} (Tcl) and {\tt wish} (Tcl incl. Tk); you need these two programs to install and run \xtem.

The current version of xtem and of Tcl is displayed by left mouse click at the \Button{help} in the main menu of \xtem.

It is our strategy from now on: the most recent version of \xtem{} will run with the most recent main release
of Tcl/Tk and at the same time with the last version of Tcl/Tk before.




\section{Installation}\label{Installation}


\begin{enumerate}\itemsep 0ex
%%%%%
\item\label{INSTPATH}
Select an installation path, e.g.\ {}{\tt /usr/local/lib}; this path should also be used for further installations
of \xtem{} (in the following this directory is  called {\tt INSTPATH}). If you have already installed an older version of
\xtem, this should also have been done in this directory (for details \sRef{DirectoriesFiles}).
%%%%%
\item
Change to directory {\tt INSTPATH}
%%%%%
\item
Move/copy file {\tt xtem{\UL}texmenu.\vvv.tar.gz} to this directory
%%%%%
\item
Unzip and untar this file, e.g.\\
        \einr{\tt gunzip xtem{\UL}texmenu.\vvv.tar.gz;\einr tar -xv[h]f xtem{\UL}texmenu.\vvv.tar}\\
or\\
        \einr{\tt gtar -zxv[h]f xtem{\UL}texmenu.\vvv.tar.gz}\\
this will create a new directory \xtem-\vvv\quad
(the h-option for the tar command may be necessary to keep the symbolic links
in file {\tt xtem{\UL}texmenu.\vvv.tar.gz}).
%%%%%
\item
Apply patches (files {\tt xtem{\UL}texmenu{\UL}Patch{\UL}\It{yymmdd}}, \sRef{GettingXtem}) if necessary.
%%%%%
\item
Change to directory {\tt xtem-\vvv}\\
Here you will find all the files {\tt *.tcl, tclIndex, mkcommand*}, this directory must also contain
the language-specific subdirectories as specified in \Ref{DirectoriesFiles}.
%%%%%
\item
Edit file \xteminstall; check and, if necessary, modify the following settings:

{\hfuzz10pt
\renewcommand{\TL}{\\\end{tabular}\vspace{-0.99ex}\par\begin{tabular}{p{21.5mm}p{38.5mm}p{90mm}}}
                                                      \begin{tabular}{p{21.5mm}p{38.5mm}p{90mm}}
variable        & default value         &       \\\hline
\tt umask       &\tt 022                & Prevents group/other-write permission for new files.\TL
\tt INSTPATH    &\verb|""|\quad\rm(empty string)
                                        & This variable normally is an empty string, {\tt xteminstall} then will set 
                                         it correctly; you must specify the installation path explicitely if the
                                         installation isn't started from the directory including this file
                                         {\tt xteminstall} or if you use {\tt mount NFS} with different export and mount
                                         paths. 
                                         If you set this variable, you must set INSTPATH in such a way that {\bf this}
                                         file \xteminstall{} is found as {\tt\${}INSTPATH/xtem-\It{n.nn}/xteminstall}
                                         (\It{n.nn} being the current version, e.g. \MinorVersion).\TL
\tt BINPATH     &\verb|"/usr/local/bin"|& Executables and shell scripts are installed in this directory;
                                         must be included in search path variable {\tt PATH}.\TL
\tt MANPATH     &\verb|"/usr/local/man/man1"|   & In this directory the man page is to be installed.\TL
\tt WISHCALL    &\verb|"/usr/local/bin/wish"|   & Command to call {\tt wishx} (must include Tcl and Tk).\TL
\tt TCLCALL     &\verb|"/usr/local/bin/tclsh"|  & Command to call {\tt tcl} (pure Tcl, without Tk).\TL
\tt PRINTCOM    &\verb|"ABORT"|         & The print command name (without options), usually {\tt lp} (SYSV-Unix) or
                                         {\tt lpr} (BSD-based Unix, e.g. Linux). In order to force you to set this
                                         variable (correctly!), we preset-ted it to {\tt ABORT}.\TL
\tt XTERMCALL   &\multicolumn{2}{l}{{\tt"xterm -sb -sl 1024  -T xtem -n xtem"}}\\
                &                       & Command to create an xterm window (normally {\tt xterm}, maybe {\tt aixterm}
                                         under AIX etc.).\TL
\tt LANGUAGES   &\multicolumn{2}{l}{{\tt"\BrL{}german deutsch\BrR{} \BrL{}english\BrR{}"}}\\
                &                       & List of languages and possibly synonyms;
                                         the number of languages is not limited, each language is enclosed in
                                         braces and can be followed by any number of synonyms
                                         (\sRefs{Multilingual},~\ref{RunXtem} and~\ref{DirectoriesFiles}).\\
                &                       & For each of the languages (not synonyms) specified here
                                         two directories must exist:
                                         \XtP/help\UL\lang~ (with subdirectories) and \XtllP\TL
\tt DEFLANGUAGE &\verb|"german"|        & Specifies the default language (\sRef{RunXtem}); the value specified must be
                                         a language (not a synonym).\TL
\tt CC          &\verb|"gcc"|           & C-compiler for translation of C programs (e.g.
                                         {\tt changecode}, \sRef{changecode} and
                                         {\tt hyphen{\UL}show}, \sRef{hyphen_show}).\TL
\tt CC{\UL}OPTS &\verb|""|              & Options for C-compiler.\TL
\tt XiMaxBoxWidth       &\tt 120        & Maximum box width (characters) for (large) select boxes
                                         in the installation menu.\TL
\end{tabular}
}

%%%%%
\item\label{XTI}
Call shell script \xteminstall{} normally directly  {\bf from this directory}---otherwise, if you want to call
\xteminstall{} from outside, you have to set {\tt INSTPATH}.
You can run this installation as often as you want without any problems!

As \xteminstall{} must run as Bourne-Shell; the first line in \xteminstall{} is: "`\verb|#!/bin/sh|"'.
If this causes an error "`cannot execute first statement"', then e.g.\ {}call:\\
\einr{\tt sh xteminstall}\\
or\\
\einr{\tt /bin/sh xteminstall}\\
(or any other path to find a Bourne-Shell on your system).

The \InstProc{} {\tt xteminstall} will work only if symbolic links are possible on your system.
Otherwise you will have to do this item by hand. The \InstProc{} puts its messages into the xterm window
and into file {\tt xteminstall.log}.

For this step of the installation you should have write permission for the \ldots{\tt/man/man1} directory and
for the \ldots{\tt/bin/} directory (otherwise messages are given to you with the Unix commands to install
links to the \xtem{} shell script, to the man pages and to the programs {\tt changecode} and {\tt hyphen{\UL}show}).
{\bf If you don't like to run an `unknown program' as superuser, run the \InstProc{} as normal user
with write access permission for directory {\tt INSTPATH}, pay attention for the messages mentioned before and
add these links if necessary.}
Once you have installed these links as you are advised, future runs of the \InstProc{} will neither
need write access to any other directories except {\tt INSTPATH} nor will generate such messages.

This \InstProc{} will do the following:
 \begin{enumerate}\topsep0ex\parskip0ex\partopsep0ex\itemsep0.1ex\parsep0.1ex
 \item Look for the version number, look whether an old version is installed or not.
 \item Compilation of programs {\tt changecode} (\sRef{changecode}) and {\tt hyphen{\UL}show} (\sRef{hyphen_show})
        if necessary.
 \item Rename \xtem{} directories (\sRef{DirectoriesFiles}).
 \item Generation and installation of the \xtem{} shell script (\sRefs{DirectoriesFiles} and~\ref{RunXtem});
        \instimpmes\label{ISC}.\\
        If necessary, you can then modify this shell script; in this case you can
        prevent it from being overwritten by a later run of the \InstProc{} by creating a file {\tt xtemInstalled}
        in directory {\tt INSTPATH/xtem-\vvv} (Unix command `{\tt touch INSTPATH/xtem-\vvv/xtemInstalled}').
 \item Installation of programs {\tt changecode} (\sRef{changecode}) and {\tt hyphen{\UL}show} (\sRef{hyphen_show});
        \instimpmes\label{ICC}.
 \item Installation of the man page (\sRef{ManualPage}); \instimpmes\label{IMP}.
 \item Creation of the directories {\tt INSTPATH/xtem{\UL}locals{\UL}\lang/} (if necessary, \sRef{DirectoriesFiles}).
 \item The local files (\sRef{LocalFiles}) are copied to the directories {\tt INSTPATH/xtem{\UL}locals{\UL}\lang/}
        if they don't exist up to now (\sRef{DirectoriesFiles}).
 \item Variable {\tt xtermcall} in file {\tt install.vst} (\sRef{install.vst}) is compared with variable
        {\tt XTERMCALL} and modified if necessary.
 \item If there are language-dependent directories which are not to be called via the {\tt LANGUAGES} variable
        in the \InstProc{} {\tt xteminstall}, a message is given as you can save disk space.
 \item Set file access for all files ({\tt chmod}, \sRef{DirectoriesFiles}).
 \item Check whether the programs listed in \Ref{ProgramList} can be accessed or not---for this check
        environment variable {\tt PATH} must exist.
 \item Check whether the bitmaps to the \LATeX{} syntax help (\sRef{LaTeXSyntaxHelp}) can be displayed or not---for
        this check environment variable {\tt PATH} must exist.
 \end{enumerate}
%%%%%
\item
If necessary (i.e.\ {}if the \InstProc{} produced such messages in items~\ref{ISC},~\ref{ICC} or~\ref{IMP},
you should now install these files with the commands given in the messages.
%%%%%
\item\label{ICSa}
If the first (basic) part oft the installation was O.K., a (self-explaining) menu comes up in which you can select any
of the local files (\sRef{LocalFiles}) and setting files (\sRef{SettingFiles}) for editing.
If this menu doesn't come up, check and set X-authority and your {\tt DISPLAY} environment variable.
We normally call \xteminstall{} (installing version \vvv{} on computer \It{blue}, switching to user \It{tex}
for the installation in this example):\par
\verb:xauth extract - $DISPLAY | rsh -l :\It{tex blue}\verb: xauth merge - ; :\\
\verb:rsh -l :\It{tex blue}\verb: "setenv DISPLAY $DISPLAY; cd /usr/local/lib/tex/xtem-:\vvv\verb:; ./xteminstall":\par
Another successful way was for us to do the installation process as superuser.

You can call this setting-file edit-menu as often as you want without (re)doing the first part of the installation
(item~\ref{XTI}) by calling ``{\tt xteminstall settings}''.
%%%%%
\item\label{ICSb}
Parallel to item~\ref{ICSa} you should start \xtem{} (shell script \xtem, \sRef{RunXtem}); call it from your
home directory or some other subdirectory in your home area where you have \TeX{} files for tests;
the main menu of \xtem{} now has to come up.

The next step will be to click at \Button{exec mode} in the main menu of \xtem{} and to check the different versions
of \mkcommand{} (\sRef{mkcommand}). If the default of \mkcommand{} doesn't fit to your system, you should modify file 
\mkcommand{.vst} (\sRef{mkcommand.vst}), preferably by using the {\tt xteminstall} menu (see item~\ref{ICSa}).

In general you should modify the setting files this way: call ``{\tt xteminstall [settings]}''
in directory {\tt INSTPATH}, select the corresponding setting file in the menu, and in parallel call \xtem{} from
some \TeX{} test directory. Each time you call a setting menu in \xtem, the setting file(s) used are loaded from disk.
So you can test and modify the setting files ``on the fly''.
\end{enumerate}


Note: the \InstProc{} \xteminstall{} is not optimised---it's a help for you to install \xtem{} easily
and safely. (E.g.\ {}the size of some widgets of the setting-files edit-menu is fixed, some buttons need some time,
especially the ``end'' buttons; in the local file editing windows, mouse grab is working with minor restrictions!)

If you get problems at installation, you should first look at the directory and file structure and compare
it with \Ref{DirectoriesFiles} and notice our ``hot-line'', \sRef{Hotline}.

And if you find the correct way by yourself---in spite of errors or misleading formulation in this guide---%
{\bf please send an e-mail to \xtememail}.

{\bf If necessary, you may change the files described in
\Refs{Help},~\ref{LaTeXSyntaxHelp},~\ref{ProgramExecFiles},~\ref{LocalFiles},~\ref{AddingPrinterDriver};
all other files may only be changed in contact with the authors.}





\section{Multilingual \xtem}\label{Multilingual}


\xtem{} is multi-lingual; up to now we have prepared an English and a German version.

\smallskip
For each language there are two directories named\\
\begin{tabular}{ll} \tt\XtP/help{\UL}\lang/ & (with subdirectories) and\\ \tt\XtllP/ \end{tabular}\\
where \lang{} stands for the language.

In this Installation Guide we use the English texts when we refer to buttons,
thus we recommend to call the English version during your first test (call: {\tt xtem -l english} [ \fnam{} ] ).


\smallskip
You will find the language-dependent texts in files {\tt\XtP/help{\UL}\lang/button.texts}. Each text is assigned
to a variable; e.g.\ {}in {\tt\XtP/help{\UL}english/button.texts} you will find the following line\\
\einr\verb|c2al    file list|\\
By this the text ``file list'' is assigned to variable {\tt vv(c2al)}.
This array {\tt vv(\ldots)} is used in order to keep the \xtem{} source files language-independent.

\smallskip
Other languages can be added: pure text files (a lot of them!) must be translated and \xteminstall,
\Button{install xtem} must be run (in order to complete the shell script {\tt xtem}).
If you want to translate these text files, please let us know, as we would like to include further languages.




\section{Character Set}\label{CharacterSet}


In the German version of \xtem{} we use ``German umlaute'' according to the  8 bit code
DIN 66303-ARV8 (Allgemeine Referenz-Version des 8-Bit-Code)/ISO 8859-1 (ISO-Latin-1)

If necessary, you may recode (in the sequence of \"A \"O \"U {\ss} \"a \"o \"u) e.g.:\\
\einr\verb|tr '\304\326\334\337\344\366\374' '\216\231\232\341\204\224\201'|

If somebody needs recoding, please inform us (\xtememail),
we then will try to include this in the installation procedure.

An easy way to see the effect of most of the used fonts is: start \xtem; left mouse button click at ``LaTeX syntax'' in
the main menu, followed by right mouse button click in the syntax window (at any position) and left mouse button click at
``fonts used in the syntax help menu'' in the window now generated gives you a list of the character sets used for the
buttons, help texts etc.\ {}in \xtem.




\section{Directories and Files}\label{DirectoriesFiles}


File {\tt xtem{\UL}texmenu.\vvv.tar.gz} (\vvv{} stands for the version, e.g.\ {}\MinorVersion)) contains all files needed
for an \xtem{} installation, all files are prefixed by {\tt xtem-\vvv/}, {\tt INSTPATH} being the installation directory
(\sRef{Installation}):

\setlength{\unitlength}{1mm}%
\begin{picture}(165,53)(0,0)
\put(0,25){\line(1,0){5}} \put(6,24){\makebox(0,0)[lb]{INSTPATH}} \put(30,25){\line(1,0){5}}
\put(35,25){\line(1,0){5}} \put(41,24){\makebox(0,0)[lb]{/xtem-\vvv}} \put(63,25){\line(1,0){7}}
\put(70,2){\line(0,1){48}}
\put(70,50){\line(1,0){5}} \put(76,48){\makebox(0,0)[lb]{/help{\UL}english/*.hlp, button.texts (and subdirectories)}}
\put(70,45){\line(1,0){5}} \put(76,43){\makebox(0,0)[lb]{/locals{\UL}english.LRW/*.news, *.vst}}
\put(70,40){\line(1,0){5}} \put(76,38){\makebox(0,0)[lb]{/locals{\UL}english \link~locals{\UL}english.LRW}}
\put(70,30){\line(1,0){5}} \put(76,28){\makebox(0,0)[lb]{/help{\UL}german/*.hlp, button.texts (and subdirectories)}}
\put(70,25){\line(1,0){5}} \put(76,23){\makebox(0,0)[lb]{/locals{\UL}german.LRW/*.news, *.vst}}
\put(70,20){\line(1,0){5}} \put(76,18){\makebox(0,0)[lb]{/locals{\UL}german \link~locals{\UL}german.LRW}}
\multiput(70,9)(0,2){3}{\line(1,0){5}} \put(76,9){\makebox(0,0)[lb]{/\ldots{} (possibly more languages)}}
\put(70,2){\line(1,0){5}} \put(76,0){\makebox(0,0)[lb]{README*, *.tcl, mkcommand*, xtem*, \ldots}}
\end{picture}


\bigskip
After installation (starting \xteminstall, clicking at the \Button{installation}) you will find the following
directory and file structure ({\tt MANPATH} and {\tt BINPATH} are set in \xteminstall, \sRef{Installation}):

\bigskip
\setlength{\unitlength}{1mm}%
\begin{picture}(165,105)(0,0)
\put(0,102){\line(1,0){5}}\put(6,101){\makebox(0,0)[lb]{BINPATH/{\bf xtem \link~INSTPATH/xtem/xtem}}}
\put(0,96){\line(1,0){5}}\put(6,95){\makebox(0,0)[lb]{BINPATH/{\bf changecode \link~INSTPATH/xtem/changecode}}}
\put(0,90){\line(1,0){5}}\put(6,89){\makebox(0,0)[lb]{BINPATH/{\bf hyphen{\UL}show \link~INSTPATH/xtem/hyphen{\UL}show}}}
\put(0,84){\line(1,0){5}}\put(6,83){\makebox(0,0)[lb]{MANPATH/{\bf xtem.1 \link~INSTPATH/xtem/xtem.1}}}
\put(35,78){\line(1,0){5}}\put(41,77){\makebox(0,0)[lb]{{\bf/xtem{\UL}locals{\UL}english/*.news, *.vst}}}
\put(35,72){\line(1,0){5}}\put(41,71){\makebox(0,0)[lb]{{\bf/xtem{\UL}locals{\UL}german/*.news, *.vst}}}
\put(35,66){\line(1,0){5}}\put(41,65){\makebox(0,0)[lb]{{\bf/xtem{\UL}locals{\UL}}\,\ldots{\bf/*.news, *.vst}}}
\put(35,58){\line(1,0){5}}\put(41,57){\makebox(0,0)[lb]{{\bf/xtem \link~xtem-\vvv}}}
\put(35,25){\line(0,1){53}}
\put(0,44){\line(1,0){5}}\put(6,43){\makebox(0,0)[lb]{INSTPATH}}\put(30,44){\line(1,0){5}}
\put(35,25){\line(1,0){5}}\put(41,24){\makebox(0,0)[lb]{/xtem-\vvv}}\put(63,25){\line(1,0){7}}
\put(70,2){\line(0,1){48}}
\put(70,50){\line(1,0){5}}\put(76,48){\makebox(0,0)[lb]{/help{\UL}english/*.hlp, button.texts (and subdirectories)}}
\put(70,45){\line(1,0){5}}\put(76,43){\makebox(0,0)[lb]{/locals{\UL}english.LRW/*.news, *.vst}}
\put(70,40){\line(1,0){5}}\put(76,38){\makebox(0,0)[lb]{/locals{\UL}english \link~{\bf../xtem{\UL}locals{\UL}english}}}
\put(70,30){\line(1,0){5}}\put(76,28){\makebox(0,0)[lb]{/help{\UL}german/*.hlp, button.texts (and subdirectories)}}
\put(70,25){\line(1,0){5}}\put(76,23){\makebox(0,0)[lb]{/locals{\UL}german.LRW/*.news, *.vst}}
\put(70,20){\line(1,0){5}}\put(76,18){\makebox(0,0)[lb]{/locals{\UL}german  \link~{\bf../xtem{\UL}locals{\UL}german}}}
\multiput(70,9)(0,2){3}{\line(1,0){5}}\put(76, 9){\makebox(0,0)[lb]{/\ldots{} (possibly more languages)}}
\put(70, 2){\line(1,0){5}}\put(76,0){\makebox(0,0)[lb]{README*, *.tcl, mkcommand*, {\bf xtem}, \ldots}}
\end{picture}

\bigskip
Files and directories typed in {\bf bold} in the preceding figure are modified during the installation process.

This file structure is the way to keep switching among various versions as easy as possible.

Because of the symbolic link\quad\XtP{} \link~\XtP{\tt-\vvv}\quad in the file structure given above,
we use \XtP{} for \XtP{\tt-\vvv} in this manual.

All local files ({\tt*.vst, *.news}) (\sRef{LocalFiles}) are located outside of directory {\tt xtem-\vvv};
once the directories {\tt INSTPATH/xtem{\UL}locals{\UL}\lang/} have been created by \xteminstall,
they will {\bf not be overwritten} by further installations.
When the directories are created by \xteminstall{} (i.e.\ {}if these directories didn't exist before), the setting files
from your old \xtem{} installation are copied or---if there was no old \xtem{} installation
(or it could not be found, as it wasn't installed in {\tt INSTPATH})---the setting files are copied
from {\tt xtem-\vvv/locals{\UL}\lang.LRW/}; at execution time \xtem{} looks for the setting files via {\tt\XtllP/}.

Language-specific directories (\sRef{Multilingual}) may be deleted, if you don't want to use this language.

For example delete {\tt xtem-\vvv/locals{\UL}german/} and {\tt xtem-\vvv/help{\UL}german/}
if you don't want to use the German version (this will save about 1.2MB),
or delete  {\tt xtem-\vvv/locals{\UL}english/} and {\tt xtem-\vvv/help{\UL}english/}
if you don't want to use the English version (this will save about 1.2MB disk space);
in any case the shell script {\tt\XtP-\vvv/xtem} has to be modified (\sRefs{Installation} and~\ref{RunXtem}).

\bigskip
All permissions are set by the \InstProc{} (\sRef{Installation}):

{\tt
\einr chmod go-w xtem xtem/* xtem/*/* xtem/*/*/*\\
\einr chmod a+r  xtem xtem/* xtem/*/* xtem/*/*/*\\
\einr chmod a+rx xtem\\
\einr chmod a+rx xtem/xtem xtem/xtem.tcl xtem/xtem{\UL}* xtem/locals{\UL}*\\
\einr chmod a+rx xtem/help{\UL}* xtem/help{\UL}*/latex xtem/help{\UL}*/miscellaneous
}




\section{Running \xtem\,---\,the Shell Script}\label{RunXtem}

During the \InstProc{} (\sRef{Installation}) a shell script {\tt INSTPATH/xtem/xtem}
and a symbolic link to it are created ({\tt BINPATH/xtem \link~INSTPATH/xtem/xtem}),
\xtem{} is to be called the following way (see also \Ref{.xtem.vst}):

\einr{\tt xtem [ -l \lang{} ] [ \fnam[.\It{suffix}] ]}

\einr\einr\begin{tabular}{ll} \lang & \tt german | deutsch | english\\ \It{suffix} & \tt.tex |~.ltx\\\end{tabular}


\bigskip
Shell script \xtem{} specifies:
\begin{mlist}
\item
 the path to the xtem directory; the environment variable {\tt XTEMPATH} will be set to the default value by line:\\
   \einr {\tt: \$\BrL{}XTEMPATH=\$\BrL{}XTEMPATH-\It{default{\UL}path}\BrR{}\BrR{}}\\
 (the \It{default{\UL}path} is specified in the \InstProc, e.g.\ {}{/usr/local/lib/tex/xtem}),
\item
 the default language (\sRefs{Multilingual} and~\ref{DirectoriesFiles})
 by means of the variable {\tt defaultlanguage} in \xtem,
\item the Tcl/Tk shell (variable {\tt wishcall} in \xtem).
\item the (pure) Tcl shell (variable {\tt tclcall} in \xtem).
\end{mlist}



\section{Programs needed with the given Setting Files}\label{ProgramList}

The installation procedure (button `install xtem' and after modifying a setting file, i.e.\ {}button `change settings')
checks all setting files (\sRef{SettingFiles}); this check is done only if Unix environment variable {\tt PATH} exists.
If a program callable via a setting file is not found (by means of Unix command {\tt which}),
the installation procedure gives a detailed warning. It also lists the searched and found programs.


If a program called at \xtem{} run is not found, \xtem{} also gives a qualified error message.
If you want to see in detail which program is called (and the options),
you can select \mkcommand{.0} (\sRef{mkcommand}) as exec mode (this will show you only the calls via
{\tt mkCmd{\UL}wait} (\sRef{ProgramExecFiles}), it will not show you the calls via {\tt exec}).

In the following you will find an example output of this test:

{\small\hfuzz25pt
\begin{verbatim}
Check whether the programs callable via the setting files are installed or not:
   (in directories "/home/l44/x11/archive_tcl_tar/xtem-5.23/locals_*/")

dvijep  : program not found, yet can be called via locals_german/printing.vst (entry # 5, parameter 3)
lpr     : program not found, yet can be called via locals_german/printing.vst (entry # 4, parameter 6)
lpjep   : program not found, yet can be called via locals_german/printing.vst (entry # 5, parameter 6)
lpjep1  : program not found, yet can be called via locals_german/printing.vst (entry # 6, parameter 6)

dvijep  : program not found, yet can be called via locals_english/printing.vst (entry # 5, parameter 3)
lpr     : program not found, yet can be called via locals_english/printing.vst (entry # 4, parameter 6)
lpjep   : program not found, yet can be called via locals_english/printing.vst (entry # 5, parameter 6)
lpjep1  : program not found, yet can be called via locals_english/printing.vst (entry # 6, parameter 6)

Programs checked and found:
  bibtex      cat       changecode  dvidvi    dvilj        
  dvips       emacs     ghostview   gtar      gunzip       
  hyphen_show ispell    lacheck     latex     latex209       
  lp          makeindex pg          spell     tar         
  tex         texchk    tla         uudecode  vi    
  xdvi        xfig      xterm                                               

...

The following programs can be called via the setting files,
yet could not be found (`which ...'):
  dvijep     lpjep    lpjep1      lpr       tkdvi        
(for details see display above and `Installation Guide')
\end{verbatim}
}

Two `non-standard' programs for which we defined entries in our setting files, you can get from our ftp server:\\
\einr\ftpiwdtex dvidvi-1.1.tar.gz\\
\einr\ftpiwdtex texchk.tar.gz





\section{The Program {\tt changecode}}\label{changecode}

We add a program {\tt changecode.c}
(written in C, can be compiled with GNU {\tt gcc} compiler and tested under x86/SOLARIS and Linux),
which does code conversion and may be used by means of the \Button{additional programs}
(see file {\tt utility.vst}, \Ref{utility.vst}):

\begin{vstfmt}
 German umlaute & $\longleftrightarrow$ & \TeX- or German-\TeX{} commands\\
 8-bit-IBM-DOS  & $\longleftrightarrow$ & 8-bit-ISO-latin-1\\
 Unix file (NL) & $\longleftrightarrow$ & DOS-file (CR/LF)\\
 tabulators     & $\longrightarrow$             & expanded to blanks  (tabulator-stops at position 8, 16, 24, \ldots)\\
\end{vstfmt}

This program may be system-dependent by blocked read/write.
If changes are necessary for some systems, please send us an e-mail: \xtememail

It is installed by the \InstProc{} (\sRef{Installation}): 
in the directory given by variable {\tt BINPATH} a symbolic link is installed.




\section{The Program {\tt hyphen{\UL}show}}\label{hyphen_show}

We also add a program {\tt hyphen{\UL}show.c}
(written in C, can be compiled with GNU {\tt gcc} compiler and tested under x86/SOLARIS and Linux),
which looks for hyphenations done by \TeX{} and is called automatically after each \TeX{} run (if requested in the
\TeX{} settings menu) or may be used by means of the \Button{additional programs}
(see file {\tt utility.vst}, \Ref{utility.vst}).

This program may be system-dependent by blocked read/write.
If changes are necessary for some systems, please send us an e-mail: \xtememail

It is installed by the \InstProc{} (\sRef{Installation}): 
in the directory given by variable {\tt BINPATH} a symbolic link is installed.




\section{Manual Pages}\label{ManualPage}

man pages {\tt\XtP/\xtem.1} and {\tt\XtP/hyphen{\UL}show.1} are installed by the \InstProc{} (\sRef{Installation}):
in the directory given by variable {\tt MANPATH} symbolic links are installed.




\section{Online Help Information}\label{Help}

With each window (widget, button) a file with a help text is associated.
The right mouse button is consequently used only for getting (context-sensitive) help.

All help text files are to be found in the files {\tt \XtP/help{\UL}\lang/*.hlp} (\sRef{DirectoriesFiles}).

If you want to modify these help files, you might first modify procedure {\tt catFile} in file {\tt ut.tcl}
to get the file names displayed:\\
 \einr\verb| configureStateDisabled $w|\\
is to be replaced by\\
 \einr\verb| $w insert end "<$dnam>\n"; configureStateDisabled $w|

If you modify the setting files (\sRef{SettingFiles}), you possibly also have to modify some of the help files.




\section{\protect\LATeX{} Syntax Help}\label{LaTeXSyntaxHelp}

There is online hypertext syntax help for nearly all \LaTeX{} commands in the files\\
{\tt\XtP/help{\UL}\lang/miscellaneous/*.htx} and {\tt\XtP/help{\UL}\lang/latex/*.htx}
(see also variable {\tt edsyntaxhelp} in \Ref{install.vst}).

You may easily add new directories for other formats (e.g.\ {}{\tt\XtP/help{\UL}\lang/tex/*.htx})
after modifying {\tt\XtP/help{\UL}\lang/miscellaneous/*.htx}. For details see file {\tt SyntaxHelp{\UL}htx.tex}

For most of these files there exist examples and dvi-files+bitmaps with the \LaTeX{} output for these examples.
The bitmaps were generated from the dvi files by means of {\tt xv}
(grabbing from an xdvi or ghostview representation of the dvi file),
saved in the files {\tt\XtP/help{\UL}\lang/latex/*.xbm}
and packed with \mbox{\tt gzip -9} \ldots{} into {\tt\XtP/help{\UL}\lang/latex/*.xbm.gz}.
When a bitmap is to be displayed, a copy will be unpacked and displayed, the unpacked file is deleted after this.

You may unpack all these files, this will take a lot of disk space,
but it will save the (small) delay caused by unpacking when syntax helps are used.

You may also delete all files {\tt\XtP/help{\UL}\lang/latex/*.xbm*} (i.e.\ {}both packed and unpacked);
in this case the files {\tt\XtP/help{\UL}\lang/latex/*.dvi} are displayed by means of the program {\tt xdvi}.

If neither {\tt gunzip} nor {\tt xdvi} is available at your installation, you have to modify procedure
{\tt hlpWinBitmap} in file {\tt ts.tcl}. In this case, please inform us so that we can extend this file for
future releases: \xtememail


\subsection{Help by Means of a Browser Call (e.g.\ {}``teTeX online help'' via Netscape)}\label{HelpBrowser}

It's possible to call URL's by means of a browser call (e.g.\ {}Netscape), up to now this facility is used in the
top level menu of the syntax help (i.e.\ {}in file {\tt\XtP/help{\UL}\lang/miscellaneous/mainhelp.htx}).

As an example we give the (local) call of the \TeX{} help integrated in teTeX:\\
{\small\verb|  @@URLtag {file:/usr/share/texmf/doc/helpindex.html 0 \|}\\
{\small\verb|            `The TeX System' -- more help to TeX/LaTeX (by ... ) }|}\\
the same, yet with path search by means of {\tt kpsewhich} or (in case of unsuccessful {\tt kpsewhich} search)
{\tt kpsexpand} instead of absolute path specification:
{\small\verb|  @@URLtag {file:_SUBSTCOM_ 2 \|}\\
{\small\verb|            {kpsewhich "-format=TeX system documentation" helpindex.html}  \|}\\
{\small\verb|            {kpsexpand "$TEXMF" /doc/helpindex.html}  \|}\\
{\small\verb|            `The TeX System' -- more help to TeX/LaTeX (by ... ) }|}\\
and the call of a remote URL:\\
{\small\verb|  @@URLtag {http://www.cogs.susx.ac.uk/cgi-bin/texfaq2html?introduction=yes 0 `TeX-FAQ' -- by ... }|}

These buttons are generated only if a browser call will be successful: for this you have variable(s)
{\tt urlcallexec(\It{i})}, \sRef{install.vst}. By means of these variables you can specify as many browsers as
you want; the browsers are called exactly in the sequence of \It{i}=1,~2,~\ldots{} up to first successful
browser call. In the case you are using Netscape it's important to first have the call 
``{\tt netscape -remote openURL(will\UL be\ldots)}'' and after this call 
``{\tt netscape will\UL be\UL replaced\UL on\UL the\UL fly\UL by\UL URL \&}'' (avoiding annoying pop-up-error-boxes
in case of an already existing Netscape session).

The text string ``{\tt will\UL be\UL replaced\UL on\UL the\UL fly\UL by\UL URL}'' will be replaced (as the string says!)
by the URL specified in ``{\tt @@linktag} \ldots''. Variable {\tt\${}TEXMF} will be expanded by the value given to this
environment variable (in case of teTeX installations automatically by ``\,\verb|kpsexpand '$TEXMF'|\,'').

The argument of the {\tt @@linktag} command (enclosed in braces and separated by a blank from the command keyword) must
have the URL at the first position; all the rest is displayed as URL-tag-text.





\section{Program Execution: \mkcommand{} Installation}\label{mkcommand}

In \xtem, program execution---especially of those programs which need interaction (terminal input and output) like
{\tt tex},  {\tt dvips} etc.---is done by calls of a procedure {\tt mkCmd{\UL}wait} (\sRef{ProgramExecFiles}).
This procedure should be as efficient as possible and is system-dependent; for this there exist different versions,
each of them is realized in one of the the files {\tt\XtP/mkcommand.\It{n}*} (\It{n} = 0, 1, 2, 3, 4, 5, 6, 9)
which are described in this section.

You have to check the following list (and probably test some versions) and then you have to modify the setting file 
{\tt\XtllP/mkcommand.vst} (\sRef{mkcommand.vst}): you have to 
\begin{mlist}
\item   remove all versions which don't work properly on your system from 
        this setting file by removing the corresponding lines and
\item   put this version of \mkcommand{} at the top position which you want to be the default one.
\end{mlist}

{\bf If it works properly on your system, we recommend \mkcommand{.6} or {\tt.7} (with Tcl $\geq$7.5).},
and \mkcommand{.3} (with Tcl 7.4).


Please help us to complete the following ``release notes'';
especially we are very interested in getting response from  NetBSD  implementations.


\newcommand{\needs}[1]{\item[needs:] #1}
\newcommand{\runswith}[1]{\item[runs with:] #1}
\newcommand{\runsnotwith}[1]{\item[doesn't run with:] #1}
\newcommand{\tested}[1]{\item[tested:] #1}
\newenvironment{mklist}%
        {\begin{list}{$\bullet$}{\topsep0.1ex\parskip0.5ex\partopsep1ex\itemsep0.1ex%
                \parsep0.1ex\leftmargin 8em\setlength{\labelwidth}{.95\leftmargin}\rightmargin 1em}}%
        {\end{list}}


\mkAbschnitt{mkcommand.0}

Version for demonstration: when a program call is started, the command
is displayed (together with the option string etc.), yet the program call is not executed.
\begin{mklist}
 \needs{Tcl, Tk}
 \runswith{all systems}
\end{mklist}


\mkAbschnitt{mkcommand.4}

Full functionality; it generates an xterm window and Tk-send-commands.
(runs with a maximum of performance with---at least we hope---all systems). 
If you have problems, check variable {\tt xtermcall} in file {\tt\XtllP/install.vst} (\sRef{install.vst}, 
the variable will be set by the \InstProc, \sRef{Installation}).

\begin{mklist}
 \needs{Tcl, Tk, X-Server with

 a) ``xauth-style authorisation'': see Unix commands {\tt xhost} and {\tt xauth} etc., get also files {\tt Xauthority}
        and {\tt xsecurity.ps.gz} from {\tt\ftpiwdpub tcl/docs/} or

 b) Tk compiled with {\tt -DNO{\UL}SECURITY}; we strictly warn you: don't use version b), this version is only to be used
        for testing purposes in a secure environment.  Version a) conforms with the strict security concept of X11R5.}

 \runswith{most Unix systems}
 \tested{%
        Apollo~Domain~OS/Unix~HP9000/400,
        DEC~3000/300LX~-OSF/1~v3.2,
        HP-UX~HP9000/700 with minor restrictions, Linux,
        SGI~Irix~5.3 with minor restrictions,
        SPARC{\UL}SOLARIS2.3
        }
\end{mklist}


\mkAbschnitt{mkcommand.5}

Full functionality; it generates a new xterm window for each program call. The xterm window is removed by $<$Return$>$ 
in the xterm window after program termination.
(This behaviour may easily be changed in the file {\tt xtem{\UL}prog} by the local administrator.)

\begin{mklist}
 \needs{Tcl, Tk}
 \runswith{all systems}
 \tested{%
        Apollo Domain~HP9000/400,
        DEC-Alpha~OSF/1~3.0, 
        DEC~3000/300LX~-OSF/1~v3.2, AIX~3.2.5,
        HP-UX~HP9000/700, SGI~Irix~5.3,
        Linux 2.0.15,
        SPARC{\UL}SOLARIS2.3,
        SPARC{\UL}SOLARIS2.5,
        X86{\UL}SOLARIS2.6
        }
\end{mklist}



\mkAbschnitt{mkcommand.6}

Full functionality; reading from Unix is done in blocks, output is written into the text message widget of xtem in 
blocks. High performance. These are test versions as successor for \mkcommand{.3} with Tcl $\geq$7.5.
\begin{mklist}
 \needs{Tcl, Tk}
 \runswith{Tcl $\geq$7.5: all systems; Tcl 7.4: most systems}
 \runsnotwith{Linux 1.0.? (Tcl7.4)}
 \tested{%
        IBM AIX 3.2 (Tcl7.4),
        Linux 1.2.13 ELF (Tcl7.5, Tcl7.6, Tcl8.0),
        Linux 2.0.15 (Tcl7.5, Tcl7.6, Tcl8.1),
        SGI Irix 5.3 (Tcl7.5),
        SPARC{\UL}SOLARIS2.5 (Tcl7.4, Tcl7.5, Tcl7.6, Tcl8.0),
        SunOS 4.1.3 (Tcl7.5),
        x86{\UL}SOLARIS2.6 (Tcl8.0)
        }
\end{mklist}






\section{User Interfaces for Program Execution (Program Calls)}\label{ProgramExecFiles}

The following files in directory {\tt\XtP/} may be adjusted by the local administrator to the local installation;
all these files are simple-structured and contain only simple Tcl-Shell-script-commands
(i.e.\ {}they do not contain the more complicated Tk-widget-commands) and are used as the interface for program calls:

\newcommand{\ttline}[1]{\einr{\tt#1\\\strut}}
 \ttline{bibliogr.tcl}
 \ttline{editor.tcl}
 \ttline{index.tcl}
 \ttline{logfile.tcl}
 \ttline{newsfile.tcl}
 \ttline{preview.tcl}
 \ttline{printing.tcl}
 \ttline{prt{\UL}*.tcl}
 \ttline{spellcheck.tcl}
 \ttline{syntax.tcl}
 \ttline{tex.tcl}
 \ttline{utility.tcl}
 \ttline{process.tcl     \rule{5em}{0em}\rm(please inform us if modification is necessary!)}
 \ttline{xtem{\UL}prog}

Each of these files includes a procedure which in generally is called with 2 parameters:
\begin{mlist}
\item[1.] text widget name (variable {\tt f}), into which the output of the program and further messages are written.
\item[2.] string variable {\tt austext}, into which in this procedure text may be written by means of variable {\tt a}.
\end{mlist}
More variables can be accessed by means of {\tt global} commands.


Most of the Tcl commands used in these files are self-explaining.
Unusual to the newcomer in Tcl may be:

\begin{vstfmt}
 \tt glob -nocomplain -- *      & unsorted file-list of the current directory\\
 \tt lsort \ldots               & sorting a list\\
\end{vstfmt}

If new procedures are added, their names must be added to file {\tt\XtP/tclIndex} too.

\medskip
For program calls (execution of Unix commands) you may select among the following
(when editing, previewing or log-listing is called, the variables {\tt edback},  {\tt prback} or {\tt logback} specify
whether the command is to be executed in background or not):

{\hfuzz30pt
\begin{mlist}
\item   \einr\verb|eval mkCmd_wait $f |\It{command}{\tt{} \bsl[list \It{options}\bsl]}\qquad\qquad or
\item   \einr\verb|     mkCmd_wait $f |\It{command}{\tt{} [list "\It{options}"]}\qquad\qquad or
\item   \einr\verb|eval mkCmd_wait $f |\It{command}{\tt{} [list "\It{options}"]}

        Examples (call of {\tt dvips} and {\tt ls}):\\
        \einr\verb|     mkCmd_wait $f dvips [list "$prtoptions $mainfile"]|\\
        \einr\verb|     mkCmd_wait $f ls [list ""]|

        The 2nd argument of {\tt mkCmd{\UL}wait} is the command to be executed, the string following
        the keyword list (enclosed in {\tt"\ldots"}) is taken for the option list of this command.
        If the command is to be called without parameters, there must be an empty list as in {\tt ls} example.

        Programs started by {\tt mkCmd{\UL}wait} are executed with current version of {\tt mkcommand} (\sRef{mkcommand}).
        The output of the command is put into the widget {\tt f} (normally passed to the calling procedure as an
        argument), the normal user-dialog is possible in this widget (e.g.\ {}with \TeX{} program in error case).

        The process-Id of the last generated process (only if generated by {\tt mkCmd{\UL}wait)} is available
        in a variable, thus killing of a running process is possible: \Button{cancel} in the main menu.

        Processes generated by mkCmd{\UL}wait may also be terminated as usual:
        \It{Ctrl-}{\tt d} (=EOF) or \It{Ctrl-}{\tt c} (=interrupt).

        Error output of the command ({\tt stderr}) is put into the same widget,
        by choice in another font type (variable {\tt fonterr} in file {\tt install.vst}, \sRef{install.vst}).

\item   \einr{\tt eval catch "exec \It{program{\UL}with{\UL}options}" \It{variable{\UL}program{\UL}output}}
\item   \einr{\tt eval set \It{variable{\UL}return{\UL}code}\\
        \hspace*{0.2\textwidth}[catch "exec \It{program{\UL}with{\UL}options}" \It{variable{\UL}program{\UL}output}]}\par

        Examples ({\tt dvips} call):

        \einr\verb|eval catch "exec dvips $mainfile.dvi" message| \\[1ex]
        \einr\verb|eval catch "exec dvips $mainfile.dvi" message|\\[1ex]
        \einr\verb|eval set res [catch "exec dvips $mainfile.dvi" message]|

        \medskip
        The \It{program} is called and its output is stored in \It{variable{\UL}program{\UL}output}
        {\bf after program termination} (which may then be passed to the text message widget).
        You may likewise call programs which generate their own window (such as {\tt xdvi, ghostview, emacs}).

        Example (call of an editor (stored in {\tt editor}) 
        which must run in an {\tt xterm} window (e.g.\ {}{\tt vi})):\\
        \einr{\tt eval set res [catch "exec xterm -e \${}editor \${}edoptions \${}ed{\UL}file \${}edback" message]}

        Calling with {\tt eval} is recommended and is necessary if an option string may be empty.
        Otherwise, in case of an empty option string, there would be an additional empty parameter,
        which causes problems e.g.\ {}for {\tt emacs, vi} and some printer drivers!

        Program calls using {\tt catch} give different results in {\tt res} and {\tt message}
        (names of these two variables according to the preceding examples):\\
        \begin{vstfmt}
        foreground call:        & \tt res       & $\leftarrow$ return code\\
                                & \tt message   & $\leftarrow$ standard output (stdout) and error output (stderr)\\
        background call:        & \tt message   & $\leftarrow$ PID\\
        \end{vstfmt}
        For more details see the Tcl man pages.
\end{mlist}
}

Output may be put into the text message widget by means of the procedures:\\
\einr{\tt\begin{vstfmt} writescr & \$f \It{text}\\      writescr0 & \$f \It{text}\\     \end{vstfmt}}\\
The 1st parameter {\tt f} being the variable name which contains the text message widget name.
Normally \It{text} should be enclosed in double-quotes.
{\tt writescr0} will put \It{text} into the widget starting at line 0,
(i.e.\ {}all previous text will be erased), otherwise \It{text} is appended.


\medskip
\samepage{Process administration is done by means of the following variables:\\
{\tt\begin{vstfmt}
 \rm variable name      & \rm value     & \\
 \hline
 sub            & 0     & \rm No foreground processes are active
                         (most buttons unlocked except `cancel' and buttons with active background process(es)).\\
                & 1     & \rm One or more foreground processes are active
                         (all buttons locked except `cancel' and `unlock').\\
 p{\UL}mkCmd    &\It{PID}       & \rm Process Id of the process which was last started by {\tt mkCmd{\UL}wait} until
                                 termination;\\
                & 1     & \rm otherwise.\\
 edsubback      & 0     &\rm No editor (started in the background by \xtem) is active (i.e.\ {}= 0 until call of
                         an editor in the background by \xtem; will be reset to 0, when \xtem{} notices that all editors
                         started by \xtem{} are no longer active.\\
                &\It{PID}       & \rm Editor was started in the background by \xtem; if more than one editor was started,
                                 this is the \It{PID} of the last started editor call.\\
 prsubback      &       & \rm Same as {\tt edsubback}, for preview program. \\
 qdsubback      &       & \rm Same as {\tt edsubback}, for \quickdirty-preview program.
\end{vstfmt}}
}
\pagebreak[1] 




\section{The Local Files: News Files and Setting Files}\label{LocalFiles}

All the following files \texttt{*.news} and \texttt{*.vst} can be modified by calling the installation 
procedure {\tt xteminstall settings} (\sRef{Installation}: items~\ref{ICSa} and~\ref{ICSb}).

\subsection{News Files: *{\tt.news}}\label{NewsFiles}

There are 2 news-files, both located in {\tt\XtllP/} and being pure text files:

\begin{vstfmt}
 file name              & displayed at\\
\hline
 \tt xtemstart.news     & \xtem{} start\\
 \tt local.news         & mouse click at \button{local news}\\
\end{vstfmt}

With these files a pin-board for \TeX{} news is given to the local administrator.



\subsection{Setting Files: *{\tt.vst}\,---\,{}Common Remarks}


The setting files described in section~\ref{SettingFiles} in detail mostly contain selection lists for programs together
with specifications like option strings (e.g.\ {}{\tt preview.vst}, \Ref{preview.vst}), suffixes for file selection
(e.g.\ {}{\tt editor.vst}, \Ref{editor.vst}), \TeX{} formats (e.g.\ {}{\tt texfmt.vst}, \Ref{texfmt.vst}) etc.

They must be adapted to the local situation by the local administrator {\bf if necessary}---yet many files need not
to be modified. We recommend just to start \xtem{} (after running the \InstProc, \sRef{Installation})
and look what happens.
If necessary, the setting files can be modified (by means of the \InstProc, \Button{change settings}) `on the fly': 
each time a setting menu is built up during \xtem{} run, the corresponding setting files are read from disk.

In most cases the first lines with settings will be taken as the local
installation default values, as described below with each setting file.

The setting files are located in 
{\tt\XtllP/}.
If necessary, each institute/department (or every single user) may have its own complete set of setting files and 
customise it. For this there is the environment variable {\tt XTEMVSTDIR}: if this environment variable exists, 
its value must be the (qualified) path name to a directory. A setting file is searched first in this
directory, if it is not found, the file contents from the directory {\tt\XtllP/} are taken.


\subsection{Setting Files: *{\tt.vst}\,---\,The Syntax}

First a remark concerning the structure of the setting files described in section~\ref{SettingFiles}
(setting of default values): 
Most of the files have a ``dummy line'' as first line: the first non-blank character of this line is taken as the 
``{\bf field separator}'' for this file, that means the parameters in the following lines must be
separated by this character (this character must not be used otherwise in this file).

Following lines: In the columns 1 to \nnn{} you set the text, which is used as a description in the text widgets/select 
boxes. Internally these texts are used for identification purpose, thus the texts must be unique in each file 
(i.e.\ {}no 2 lines are allowed to have the same texts). The number \nnn{} given for each file need not strictly to be
observed. It means that the contents of these columns will be displayed in the selection box. If the text string is 
longer than \nnn{} characters, the full text will be displayed when you press the \Button{display preferences} in the 
setting menu.  If the text string has less than \nnn{} characters, the only effect will be that the field separator
character and eventually parts of the following parameters will be visible to the user in the select box. 
In all cases \xtem{} works identically.

The last parameter may be followed by a field separator.

{\bf Evaluation of the setting files is stopped at the first empty (or blank) line.}
By this you may have any number of ``comment'' lines at the end of your file, serving as model lines etc.

{\bf Lines may be split in most of the setting files}
(backslash as last non-blank character in the line to be continued).
Excepted from this splitting is file {\tt install.vst}.
You can use this line splitting/continuation and so insert a `pseudo blank line' after an entry in order 
to make the setting files more readable.
The \InstProc{} inserts into most of the setting files these ``pseudo blank lines'' at file saving!

{\bf You can avoid problems (especially arising from inserting unintended empty lines or forgetting a backslash as line 
continuation) if you only edit the setting files by means of the \InstProc{} (\sRef{Installation}, item~\ref{ICSa}).}

In the following descriptions the variable names are given in {\tt teletype}, if they are used in the Tcl source code 
files which may be modified by you (\sRef{ProgramExecFiles}). Most of them are to be found in the setting files 
{\tt HOME/.xtem{\UL}\lang.vst} and {\tt\fnam{\UL}\lang.vst} (generated by \xtem, \sRef{.xtem.vst}).

\medskip
If you modify the setting files, you possibly also have to modify some of the help files (\sRef{Help}).


\subsection{Setting Files: *{\tt.vst}\,---\,{}All Files in Detail}\label{SettingFiles}

\vstfile{0}{bibtex.vst}{Bibliography}{Bibliography preparing program}\label{bibtex.vst}

\FALines
\begin{vstfmt}
                & \tt bitext    & Text (\nnnch{45}).\\
 \param{1st}    & \tt bibtex    & Bibliography preparing program.\\
 \param{2nd}    & \tt bioptions & Option string for the bibliography preparing program.\\
\end{vstfmt}
\DefLine{2nd}

\ButSup{b{\UL}bibliography}


\vstfile{1}{cleanup.vst}{Cleanup}{Suffixes for clean up window}\label{cleanup.vst}
 
\FALines
\begin{vstfmt}
                & \tt aufsuff   & File suffix: candidates for clean up, (\nnnch{10}).\\
 \param{1st}    & \tt auftoggle & {\tt 0 | 1}\\
                & \tt           & 0: Suffix is inactive by default.\\
                & \tt           & 1: Suffix is active by default.\\
\end{vstfmt}


\vstfile{1}{editor.vst}{Editor}{List of editors}\label{editor.vst}

\FALines
\begin{vstfmt}
                & \tt edtext    & Text (\nnnch{50}).\\
 \param{1st}    & \tt edxterm   & Name of the xterm window and parameters for call,
                                 if editor needs an xterm window (e.g.\ {}{\tt vi}), blank otherwise.\\
 \param{2nd}    & \tt editor    & Editor (called in the background if followed by \&).\\
 \param{3rd}    & \tt edoptions & Editor call option string.\\
\end{vstfmt}
\DefLine{2nd}

If you insert new editors, you should also check file {\tt tex.tcl}
for the editor call via the {\tt e} option at errors during \TeX{} run.


\vstfile{1}{hyphen.vst}{Hyphenation}{Hyphenation check program}\label{hyphen.vst}

\FALines
\begin{vstfmt}
                & \tt hyphentext  & Text (\nnnch{8}).\\
 \param{1st}    & \tt texposthyph & {\tt 1 | 0} : After \TeX-run {\tt hyphenprog} is started automatically or not.\\
 \param{2nd}    & \tt hyphenprog  & Name of the hyphenation check program.\\
 \param{3rd}    & \tt hyphenopts  & Options for the hyphenation check program call.\\
 \param{4th}    & \tt hyphenchk   & File name (containing already checked hyphenations).
                                         {\tt /dev/null} is allowed for this variable.\\
\end{vstfmt}
\DefLine{2nd}

In \param{4th} ({\tt spoptions}) you can use variable {\tt \${}mainfile} 
(in order to use a file with (already) checked hyphenations specific for the main file to be \TeX'ed)
or variable {\tt \${}env(HOME)} (in order to locate this file in the home directory).



\vstfile{1}{index.vst}{Index}{Index preparing program}\label{index.vst}

\FALines
\begin{vstfmt}
                & \tt intext    & Text (\nnnch{55}).\\
 \param{1st}    & \tt index     & Index preparing program.\\
 \param{2nd}    & \tt inoptions & Option string for the index preparing program.\\
\end{vstfmt}
\DefLine{2nd}

In \param{2nd} ({\tt inoptions}) you can use variable {\tt \${}mainfile}
(e.g.\ {}in order to redirect {\tt stdin} and {\tt stdout}, as required with some implementations of makeindex).

\ButSup{b{\UL}index}


\vstfile{1}{install.vst}{Common Installation Settings}{Installation parameters}\label{install.vst}
 
The following variables may be set in this file (one variable per line, the variable value is separated by at least one
blank from the variable name; lines in this file may not be continued (splitted);
lines starting with a \# are ignored (comment lines)).

{\hfuzz10pt
\renewcommand{\TL}{\\\end{tabular}\vspace{-0.99ex}\par\begin{tabular}{p{\vn}p{\vv}}}
                                                      \begin{tabular}{p{\vn}p{\vv}}
 variable name  &  variable value\\
\hline
 \tt b{\UL}spell                & {\tt 1 | 0} : Spell button in xtem main menu to be created or not.\TL
 \tt b{\UL}syntax               & {\tt 1 | 0} : Same for syntax check button.\TL
 \tt b{\UL}index                & {\tt 1 | 0} : Same for make index button.\TL
 \tt b{\UL}bibliography & {\tt 1 | 0} : Same for bibliography (bibtex) button.\TL
 \tt b{\UL}additional   & {\tt 1 | 0} : Same for additional programs button.\TL
 \tt b{\UL}logfile              & {\tt 1 | 0} : Same for logfile button.\TL
%\tt b{\UL}letters      & {\tt 1 \It{button text} | 0} : Same for ``letter'' button.\TL
 \tt bell{\UL}level& {\tt 1 | 2 | 3 | 4} : different levels for the bell.\TL
                & 1 : warnings and errors result in a bell signal.\TL
                & 2 : errors only result in a bell signal.\TL
                & 3 : severe errors only result in a bell signal.\TL
                & 4 : no bell signal at all.\TL
 \tt bindAltMeta        & {\tt 1 | 0} : Alt-key and Meta-key bindings are equivalent or not. This is useful, as some
                         X11 installations define Alt-key, whilst other installations define Meta-key.\TL
 \tt bindkeysenab& {\tt 1 | 0} : Key binding is enabled or not. Key binding allows you to use keystrokes instead of
                  mouse-clicks for some buttons in the main menu and to use PageUp, PageDown etc.\ {}for positioning
                  in the main menu.\newline
                  Key bindings can be defined in file {\tt install.vst} by means of the variables 
                  {\tt bindkeys(}\ldots{\tt)} (see below). 
                  Two parameters (separated by at least one blank) can be assigned to each variable.
                  The first parameter specifies the event, for which you normally can use {\tt Alt-Key-}\It{key} or
                  {\tt Control-Key-}\It{key}, the second parameter gives a text (abbreviation) to be inserted
                  in the button texts in the main menu.\TL
 \tt bindkeys(.b.2.ts)  & Key binding for TeX syntax help menu call.\TL
 \tt bindkeys(fs)& Key binding for file selection menu call.\TL
 \tt bindkeys(ed)& Key binding for editor call.\TL
 \tt bindkeys(qd)& Key binding for \quickdirty{} run.\TL
 \tt bindkeys(la)& Key binding for \TeX/\LaTeX{} program call.\TL
 \tt bindkeys(pr)& Key binding for preview program call.\TL
 \tt bindkeys(as)& Key binding for print menu call.\TL
 \tt bindkeys(au)& Key binding for clean up menu call.\TL
 \tt bindkeys(re)& Key binding for spell check program call.\TL
 \tt bindkeys(sy)& Key binding for syntax check program call.\TL
 \tt bindkeys(in)& Key binding for index preparing program call.\TL
 \tt bindkeys(bi)& Key binding for bibliography preparing program call.\TL
 \tt bindkeys(so)& Key binding for utility menu call.\TL
 \tt bindkeys(fl)& Key binding for logfile display.\TL
 \tt button2end & {\tt 2} :  Button-2 (middle mouse button) instead of Button-1 (left mouse button) will not only select
                 an item from a list box or a list of radiobuttons, but will in addition end the setting menu 
                 (``expert mode click'')---realized where useful and unique.\TL
                & {\tt 0} : otherwise.\TL
 \tt edsyntaxhelp & {\tt yes | icon | no}.\TL
                & {\tt yes} : When the editor is called, an extra window with Hypertext syntax help to the \LATeX{} 
                 commands will be created (only for those \LATeX{} formats, for which a directory 
                 {\tt\XtP/help{\UL}\lang/\It{format}{\UL}syntax/} is present; 
                 at the moment there is only \LaTeX{} syntax help).\TL
                & {\tt icon} : Same as {\tt yes}, but window will be created as icon.\TL
                & {\tt no} : Window will not be created automatically.\TL
                & The user can change this in the editor setting menu.\TL
 \tt errbgrd    & Background colour used for marked text (error position) in error editor (logfile analyse).\TL
 \tt errfgrd    & Foreground colour used for marked text (error position) in error editor (logfile analyse).\TL
 \tt exallowset & {\tt 1 | 0}\,;
                 1 : Setting menus can be called during \LATeX{} runs etc., 
                 0 : otherwise.\TL
 \tt fontbl     & Font used for buttons/labels.\TL
 \tt fontstdout & Font used for {\tt stdout} program-run output and for standard output in text widgets.\TL
 \tt fonterr    & Font used for {\tt stderr} program-run output.\TL
 \tt fontdli    & Font used for selection boxes.\TL
 \tt fontsli    & Font used in printer selection (criteria selection).\TL
 \tt fonterrtag & Font used for error tags generated at logfile-analyse.\TL
 \tt fonted     & Font used for logfile-analyse-editor window.\TL
 \tt fsmenucols & {\tt 2 | 3} :  2 or 3 select-boxes in the file selection menu
                  (i.e.\ {}the directories and the \TeX-files are displayed in one selection-box or separately).\TL
 \(\left.\hspace*{-0.15em}\parbox{9.4em}{%
  \tt hlp{\UL}font(normal)      \\
  \tt hlp{\UL}font(tag)\\
  \tt hlp{\UL}font(bold)\\
  \tt hlp{\UL}font(boldlrge)\\
  \tt hlp{\UL}font(teletype)\\
  \tt hlp{\UL}font(telelrge)\\
  \tt hlp{\UL}font(telesmll)\\
  \tt hlp{\UL}font(italic)
 }\right\}\) & Fonts used in \LATeX{} syntax help, see {\tt SyntaxHelp{\UL}htx.tex}.\TL
 \tt maxprintcops       & Maximum number of print-copies.\TL
 \tt mdispmain  & {\tt 1} : in the file selection menu you get 2 buttons to reduce the main file list (files including
                 a {\tt$\backslash$documentclass} or {\tt$\backslash$documentstyle} command)---only if variable
                 {\tt mainfilgrep} for the (La)TeX format selected (\sRef{texfmt.vst}) provides for this.\TL
                & {\tt 0} : else.\TL
 \tt mdispmainv & {\tt 1} : reduced list as default for the main file selection list (see variable {\tt mdispmain}).\TL
                & {\tt 0} : full list as default for the main file selection list.\TL
 \tt mousebutts & {\tt 2 | 3} :  Number of mouse buttons;
                 if 2: Control-RigthMouseButton emulates the missing (middle mouse) button.\TL
 \tt noWarnTcl  & \It{Tcl{\UL}version} (e.g.\ {}7.7). If you run \xtem{} with a Tcl version with which we couldn't test
                 \xtem{} up to now, a warning is given at \xtem{} start. By setting this variable to the Tcl version you
                 can suppress this warning.\TL
 \tt prtfilperm & {\tt non-permanent | permanent} (language-dependent, see below).\TL
                & {\tt non-permanent} : The file to be printed ({\tt prt{\UL}\fnam}) will be deleted after printing.\TL
                &{\tt permanent} : The file to be printed ({\tt prt{\UL}\fnam}) will not be deleted after printing.\TL
                & These values must be identical with the strings given to the variables {\tt dm19} or {\tt dm20} 
                 in file {\tt\XtP/help{\UL}\lang/button.texts}.\TL
 \tt prtlistsort& {\tt 0} : printer list in the printer selection menu displayed in order given by file printing.vst,\TL
                  {\tt 1} : printer list sorted alphabetically by default.\TL
 \tt prtselmaxc & Maximum number of characters fitting into screen
                 (using font {\tt fontsli}) for printer list reduction.\TL
 \tt prtselmaxl & Maximum number of lines in criteria lists for printer list reduction 
                 (if more entries are found, a scrollbar is generated).\TL
 \tt quickdelfile & {\tt 0} :  \quickdirty-files are to be deleted in menu \Button{clean up} only,\TL
                  & {\tt 1} : at leaving of \xtem{} or\TL
                  & {\tt 2} : immediately after \quickdirty{} run.\TL
 \tt quickfile    & File name used for \TeX'ing etc.\ {}with \Button{\quickdirty}.\TL
 \tt quickmultprv & {\tt 0} : 1 preview window at most for (subsequent) \quickdirty{} runs.\TL
                  & {\tt 1} : more than 1 preview window for \quickdirty{} allowed.\TL
 \tt quicknonstop & {\tt 1} : \quickdirty{} \TeX{} run is forced in nonstop mode,\TL
                  & {\tt 0} : else.\TL
 \tt quickprev    & {\tt current{\UL}preview | standard{\UL}preview} : specifies the \quickdirty{} default preview.\TL
                  & {\tt current{\UL}preview} : the current preview (\Button{preview}) is used as preview for \quickdirty
                    as well.\TL
                  & {\tt standard{\UL}preview} : the preview specified by {\tt quickprevstd} is used as preview
                   for \quickdirty.\TL
 \tt quickprevstd & standard preview for \quickdirty; if an empty string is given as standard preview, \quickdirty{} is
                   forced to always use the current preview. The program name can be followed by preview options.\TL
 \tt quickprsstd  & {\tt.dvi |~.ps} : suffix for \quickdirty{} standard preview (needed for dvips-run in case of a
                   postscript preview like ghostview).\TL
 \tt shortbutts & {\tt 0} : `long' texts in main menu buttons.\TL
                & {\tt 1} : `short' texts in main menu left buttons,
                 `long' texts are displayed when mouse enters a button.\TL
                & {\tt 2} : `short' texts in main menu left and right buttons,
                 `long' texts are displayed when mouse enters a button.\TL
 \tt sizeds     & Size of printer list in printer settings menu.\TL
 \tt syntaxmark & {\tt 1 | 0} : After loading a \LATeX{} syntax help text into a widget, the text is positioned to the
                 selected command or not (i.e.\ {}positioned to the top of the text).\TL
 \tt texautostrt        & {\tt 1 | 0} : If this variable has value 1, radiobuttons in the "`TeX settings"' menu are
                         generated by which the user can modify variable {\tt texautostrtv}.\TL
 \tt texautostrtv       & {\tt 1 | 0} : If this variable has value 1, a TeX program run is started automatically after
                         the current "`edit file"' or the current `"main file"' has changed, i.e. one of these files is 
                         "`saved"' in your edit session. This variable can be modified by means of radiobuttons in the
                         "`TeX settings"' menu ()see variable {\tt texautostrt}.\TL
 \tt texedit    & If this variable is defined and its value is non-blank, this string will be passed to environment
                 variable {\tt TEXEDIT} before a \TeX{} run is started (e.g.\ {}you can set {\tt texedit} to 
                 `{\tt emacs +\%d \%d}'). If the value specified is `blank' or variable {\tt texedit} is not defined in
                 this file, {\tt TEXEDIT} will be set according to you current editor. {\tt TEXEDIT} is used for editor
                 call if you reply `{\tt e}' to an error-message during \TeX-run.\TL
 \tt texloganalyze      & {\tt 1 | 0} : After \TeX-run transcript (logfile) analyse is done 
                         (for each detected error/warning a tag will be generated) or not.\TL
 \tt texlogwarning      & {\tt 0 | 1} : "`LaTeX Warning: ..."' are suppressed or not in case of logfile analyse.\TL
 \tt texmax     & {\tt 1 | 2 | 3 | 4} :  Maximum number of TeX runs.\TL
 \tt texpostbib & {\tt 1 | 0} : After \TeX-run {\tt bibtex} (\sRef{bibtex.vst}) is started automatically
                 (if string ``LaTeX Warning: There were undefined references'' is found in~.log-file ) or not.\TL
 \tt texpostind & {\tt 1 | 0} : After \TeX-run {\tt [make]index} (\sRef{index.vst}) is started automatically
                 (if idx file was modified) or not.\TL
 \tt texpostps  & {\tt 1 | 0} : After \TeX-run {\tt dvips} is started automatically (if ghostview as previewer) or not.
                 Be careful with setting this variable to 0: if you have a ghostview preview active in background and do
                 a \TeX{} run, after this run you cannot get a refresh of your preview without leaving and restarting
                 ghostview (at restart the Postscript file will be updated!).\TL
 \tt texposttex & {\tt 1 | 0} : After automatically started {\tt [make]index} or {\tt bibtex}
                 (\sRefs{index.vst} and~\ref{bibtex.vst}) runs, one more \TeX-run is started or not.\TL
 \tt textxscroll& {\tt 2} : Vertical scrollbar (and no text wrapping) for all text widgets is generated.\TL
                & {\tt 1} : Vertical scrollbar for the text widget in \xtem's main menu only.\TL
                & {\tt 0} : No vertical scrollbar at all.\TL
 \tt tlHBadness & Integer number $\ge$ 0\TL
                & Underfull boxes exceeding this value are taken into account at transcript 
                 (logfile) analyse; the user can change this in the \TeX{} setting menu.\TL
 \tt tlDirIgnore& A qualified directory name can be given as value to this variable; files in this
                 directory and its subdirectories are ignored at transcript (logfile) analyse 
                 (supposing that the user is not allowed to edit files in this directory and its subdirectories).\TL
 \tt tlMaxLines & Integer number $\ge$ 0\TL
                & If the transcript file has more lines than this number, transcript (logfile) 
                 analyse ends at this line; the user can change this in the \TeX{} setting menu.\TL
 \tt tlOverfull & Real number $\ge$ 0.0\TL
                & Overfull boxes exceeding this value are taken into account at transcript  
                 (logfile) analyse; the user can change this in the \TeX{} setting menu.\TL
 \tt unlockbutt & {\tt 0} : unlock button in \xtem's main menu will not be generated.\TL
                & {\tt 1} : unlock button in \xtem's main menu will be generated.\TL
 \tt urlcallexec(\It{i}) & One or more Calls (by means of exec) of a browser
                 (e.g. {\tt netscape}, \sRef{HelpBrowser}.\TL
 \tt versionlerg& Text: Local appendix to the version string.\TL
 \tt whichcheck & {\tt yes | no} : Before a program call it is tested or not whether 
                 this program is found by means of the environment variable {\tt PATH} 
                 (this variable must exist if {\tt whichcheck} is set to {\tt yes}).\TL
 \tt widthl     & Width of buttons in the left half of main menu.\TL
 \tt widthr     & Width of buttons in the right half of main menu.\TL
 \tt xtermcall  & Call for an ASCII xterm, in which may be run \TeX{} etc. The installation procedure 
                 (\sRef{Installation}) modifies this line if necessary, according to the setting of {\tt XTERMCALL}
                 in file {\tt xteminstall}.\TL
\end{tabular}
}

These variables normally will be set by the local administrator.
Yet  the user may set these variables at his choice the following way: set the environment variable 
{\tt XTEMINSTALL} to the name of a file which contains your ``install.vst''. 
If so, the variables are read from the file specified in {\tt XTEMINSTALL} instead 
from the file {\tt\XtllP/install.vst}). 
For additional facilities to set fonts \sRef{Fonts}.



\vstfile{1}{logform.vst}{Transcript (Logfile) Display Mode}%
  {List of programs/commands for displaying logfiles}\label{logform.vst}
 
\FALines
\begin{vstfmt}
                & \tt logtext   & Text (\nnnch{45}).\\
 \param{1st}    & \tt logterm   & Name of the xterm window incl.\ {}options, if {\tt logform}
                                 needs an xterm window (e.g.\ {}{\tt vi}), blank otherwise.\\
 \param{2nd}    & \tt logform   & Unix-command/editor (called in the background if followed by \&).\\
 \param{3rd}    & \tt logoptions& option string for this command/editor.\\
\end{vstfmt}
\DefLine{2nd}

\ButSup{b{\UL}logfile}



\vstfile{1}{logsuffix.vst}{Transcript (Logfile) Suffix List}%
  {List of suffixes of possible transcript files/logfiles}\label{logsuffix.vst}
 
All lines:\\
\einr\It{suffix{\UL}of{\UL}logfile}\verb*| [ |\ldots\verb|]| \It{text{\UL}describing{\UL}the{\UL}logfile}

The \It{suffix{\UL}of{\UL}logfile} (variable {\tt lsuff}) and the following text must be separated
by one or more blanks; e.g.\\
\einr\verb|.log   logfile from TeX run|



\vstfile{1}{mkcommand.vst}{Program Execution}%
  {List of different forms of mkcommand procedures}\label{mkcommand.vst}

\FLine{, followed by Tcl version specifications:}
\begin{vstfmt}
                & \novar        & \Empty.\\
 \param{1st}    & \tt Tcl{\UL}\It{version1}     & Tcl version 1 (e.g.\ {}{\tt Tcl{\UL}7.4}).\\
 \param{2nd}    & \tt Tcl{\UL}\It{version2}     & Tcl version 2 (e.g.\ {}{\tt Tcl{\UL}7.5}).\\
 \ldots         &               & (the number of Tcl version specified is not limited for reasons of compatibility with
                                 old \xtem{} versions, running with older Tcl versions for instance!).\\
\end{vstfmt}

{\bf All other lines:} specification if mkcommand version(s) running with the Tcl version(s) specified in the 1st line:\\
\begin{vstfmt}
                & \novar        & Text (\nnnch{70}).\\
 \param{1st}    & \tt mksel     & mkcommand procedure running with Tcl \It{version1} and this system.\\
 \param{2nd}    & \tt mksel     & mkcommand procedure running with Tcl \It{version2} and this system.\\
 \ldots         &               & (the number of parameters (columns) depends on the 1st line.
\end{vstfmt}
\DefLine{2nd}

The Tcl version of your installed Tcl/Tk is checked automatically by \xtem; when the selection box in the ``exec mode''
setting menu is filled, only the parameter corresponding to the Tcl version (see 1st line) is taken into account.
If this parameter is empty, this line will be skipped at filling the selection box.


 
\vstfile{1}{preview.vst}{Previewing}{List of preview programs}\label{preview.vst}
 
\FALines
\begin{vstfmt}
                &               & Text (\nnnch{50}). This text must be unique to identify 
                                 this line in the file, commas (``,'') are not allowed.\\
 \param{1st}    & \tt preview   & Name of the preview program 
                                 (called in background if followed by \&).\\
 \param{2nd}    & \tt prsuffix  & {\tt.ps |~.dvi} : Preview suffix (if {\tt prsuffix} is set to 
                                 {\tt.ps}, dvips will be started automatically after a \TeX{} run; 
                                 this is important when the previewer is active in the background).\\
 \param{3rd}    & \tt proptions & Option string for this previewer.\\
 \param{4th}    & \novar        & Preview formats and options associated with this format for dvips 
                                 (necessary for postscript previewers such as ghostview) and for 
                                 the previewer itself in the syntax given below:\\
\end{vstfmt}

\einr{\tt \It{text1}\BrL{}\It{options{\UL}for{\UL}dvips}\BrR{}\BrL{}\It{options{\UL}for{\UL}previewer}\BrR{}%
        [,\It{text2}\BrL{}\ldots\BrR{}\BrL{}\ldots\BrR{}[,\ldots]]\ldots}

There may be any number of formats (at least one), i.e.\
the number of triples ``{\tt\It{text}\BrL{}\ldots\BrR{}\BrL{}\ldots\BrR{}}'' is not limited.

The format text \It{text} is displayed together with {\tt prtext}, all format texts 
from all lines are the basis for the format list in the preview setting menu. 
Use the same format texts as in {\tt printing.vst} (\sRef{printing.vst}).
\It{options{\UL}for{\UL}previewer} will be added to {\tt proptions}.
\It{options{\UL}for{\UL}dvips} is used as option string for the dvips run preceding 
preview call (in case of a postscript previewer such as ghostview).
The number of formats (at least one) is not limited; the first format specified in the preview 
format list for the default previewer (1st previewer specified) will be the default format, for 
reasons of consistency it should be equal to the printer default format (\sRef{printing.vst}).

Examples (both use A4 format in portrait and A4 in landscape): 

\begin{tabular}{ll}
a) for ghostview (needs dvips!):
             & A4{\UL}portrait\BrL{}\BrR{}\BrL{}-a4\BrR{},A4{\UL}landscape\BrL{}-t landscape\BrR{}\BrL{}-a4 -swap
                -landscape\BrR{}\\
b) for xdvi: & A4{\UL}portrait\BrL{}\BrR{}\BrL{}-paper a4\BrR{},A4{\UL}landscape\BrL{}\BrR{}\BrL{}-paper a4r\BrR{}\\
\end{tabular}


 
\vstfile{1}{printing.vst}{Printer Selection}{Printer driver and printer settings}\label{printing.vst}

\FLine{, followed by criterion headings:}
\begin{vstfmt}
                & \novar        & \Empty.\\
 \param{1st}    & \novar        & Heading for printer names (1st \crit).\\
 \param{2nd}    & \novar        & Heading for printer emulations (2nd \crit, part a).\\
 \param{3rd}    & \novar        & Heading for printer drivers (2nd \crit, part b).\\
 \param{4-10th} & \novar        & \Empty.\\
 \param{11th}   & \novar        & Heading for printing formats (3rd \crit).\\
 \param{12th}   & \novar        & Heading for 4th \crit.\\
 \param{13th}   & \novar        & Heading for 5th \crit.\\
 \ldots         &               & (the number of criteria is not limited!).\\
\end{vstfmt}\par Example (field separator `@' and heading line):\\
\verb|   @ printer @ emulation @ driver @     @          @    @       @@@@ \|\\
\verb|       format     @ double-sided     @ resolution     @ department @ colour @|

{\bf 2nd line:} default values for the criteria used for the ``printer pre-selection''.
The criteria are used in the printer setting menu and in the printer pre-selection menu.
Every single criterion you can give `*' (=wild-card as in Unix filenames) as default value.
This line must not be moved, thus the buttons to do this in the \InstProc{} (in ``change settings'') are inactive!\\
\begin{vstfmt}
                & \novar        & \Empty.\\
 \param{1st}    & \novar        & default printer name (1st \crit).\\
 \param{2nd}    & \novar        & default printer emulation (2nd \crit, part a).\\
 \param{3rd}    & \novar        & default printer driver (2nd \crit, part b).\\
 \param{4-10th} & \novar        & \Empty.\\
 \param{11th}   & \novar        & default printing format (3rd \crit).\\
 \param{12th}   & \novar        & default for 4th \crit.\\
 \param{13th}   & \novar        & default for 5th \crit.\\
 \ldots         &               & \\
\end{vstfmt}\par Example (2nd line: criteria line):\\
\verb|    @ *      @ Postscript @ dvips   @     @      @    @     @@@@ \|\\
\verb|       *       @ *                   @ *              @ *       @ sw       @|


{\bf All other lines:}\\
\begin{vstfmt}
                & \novar        & Short text for printer (\nnn$<$30); no commas `,' allowed.\\
 \param{1st}    & \tt printer   & Printer name text (1st \crit); this parameter can be used as selection criterion only,
                                 i.e.\ {}it's not used for printer routing at printing!\\
 \param{2nd}    &\novar         & Emulation name (2nd \crit, part a).\\
 \param{3rd}    & \tt prtdriver & Printer driver (2nd \crit, part b).\\
 \param{4th}    & \tt prtsuf    & Suffix for the print file.\\
 \param{5th}    & \tt prtoptions& Printer driver option string. (Especially: x-y-offset 
                                 should be correct, such as \TeX's zero will be 1 inch 
                                 below and right to the left upper edge of the paper!)\\
 \param{6th}    & \tt lpcmd     & Print command.\\
 \param{7th}    & \tt lpopt     & Print command option string.\\
 \param{8-10th} & \novar        & Empty.\\
 \param{11th}   & \novar        & Format selection specifications (3rd \crit).\\
 \param{12th}   & \novar        & Value for 4th \crit.\\
 \param{13th}   & \novar        & Value for 5th \crit.\\
 \ldots         &               & (The number of values must be the same as the headings given above!)\\
\end{vstfmt}

The \param{11th} must be of the following form:\\
\einr{\tt\It{text1}\BrL\It{options{\UL}for{\UL}printer{\UL}driver}\BrR\BrL\It{options{\UL}for{\UL}print{\UL}command}\BrR%
        [,\It{text2}\BrL\ldots\BrR\BrL\ldots\BrR[,\ldots]]\ldots}

\begin{minipage}{\textwidth}
Each \crit{} in the 12th, 13th,\ldots{} parameter has the following form:\\
  \einr{\em\crit{\UL}text}\\
or\\
  \einr{\em\crit{\UL}text\BrL{}options{\UL}for{\UL}printer{\UL}driver\BrR\BrL{}options{\UL}for{\UL}print{\UL}command\BrR}
\end{minipage}

Embedded blanks are forbidden in the \It{text} strings
(that means you should write {\tt floor{\UL}3} instead of {\tt floor 3} e.g.).
All \It{text}s from all parameters are added to {\tt prttext} and will be
displayed in the ``printer selection box'' in the ``printer settings menu''.

Braces \BrL\ldots\BrR{} are forbidden within the option text strings.\\
\It{options{\UL}for{\UL}printer{\UL}driver} will be added to {\tt prtoptions},
\It{options{\UL}for{\UL}print{\UL}command} will be added to {\tt lpopt}.

Use the same printer format texts (11th parameter) as in {\tt preview.vst} (\sRef{preview.vst}),
all printer format texts from all lines are the basis for the format list in the printer pre-selection menu.\\
There may be any number of formats (at least one), i.e.\ {}the number of triples 
``{\tt\It{text}\BrL\ldots\BrR\BrL\ldots\BrR}'' is not limited; the first format specified in the printer format 
list for the default printer (1st printer specified) will be the default format, for reasons of consistency it should 
be equal to the preview default format (\sRef{preview.vst}).

Example:\\
 \verb|HPLaserjet IV  @ xlw3 @ Postscript @ dvips @ .ps @    @ lp @  -c -dxlw3 @@@@ \|\\[0.3ex]
 \verb|   A4_portrait{}{},A4_landscape{-t landscape}{} @ \|\\
 \verb|   single-sided{}{-dsimplex},double-sided{}{}@300dpi{}{},600dpi{-P xlw3}{}@LRW@sw@|

\smallskip
You can specify a printer offset as 5th parameter, e.g.:\\[0.3ex]
 \verb|HPLaserjet IV  @ xlw3 @ Postscript @ dvips @ .ps @ -O 1.0mm,0.0mm @ lp @  -c -dxlw3 @@@@ \|\\
 \verb|   A4_portrait{}{},A4_landscape{-t landscape}{} @ \|\\
 \verb|   single-sided{}{-dsimplex},double-sided{}{}@300dpi{}{},600dpi{-P xlw3}{}@LRW@sw@|

or (if the offset is format dependent) in the 11 the parameter, e.g.:\\[0.3ex]
 \verb|HPLaserjet IV  @ xlw3 @ Postscript @ dvips @ .ps @    @ lp @  -c -dxlw3 @@@@ \|\\
 \verb|   A4_portrait{-O 1.0mm,0.0mm}{},A4_landscape{-t landscape -O 0.0mm,2.0mm}{} @ \|\\
 \verb|   single-sided{}{-dsimplex},double-sided{}{}@300dpi{}{},600dpi{-P xlw3}{}@LRW@sw@|

\bigskip
The values from the third line (if there is no printer-selection criteria line: the values from the second line)
are taken as default values for printing.




\vstfile{1}{{\tt prt{\UL}dvi\It{xxx}.vst}}{Printer Drivers}%
  {Printer specifications such as pages selection}\label{prtxxxvst}

\FALines
\begin{vstfmt}
                &               & Text (\nnnch{85}).\\
 \param{1st}    & \tt prmrelabs & {\tt r} : the user may select the start and end page to
                                 be printed as relative page numbers,\\
                &               & {\tt a} : the user may select the start and end page to
                                 be printed as absolute page numbers,\\
                &               & (blank) : all pages are to be printed, i.e.\ {}page
                                 selection is forbidden (e.g.\ {}{\tt a5booklet}).\\
 \param{2nd}    & \tt prmsel    & By this parameter the corresponding commands in procedure
                                 {\tt prt{\UL}dvi\It{xxx}} will be selected (file {\tt prt{\UL}dvi\It{xxx}.tcl},
                                 \sRefs{AddingPrinterDriver} and~\ref{ProgramExecFiles}).
                                 Which values you can use for {\tt prmsel} depends on file {\tt prt{\UL}dvi\It{xxx}.tcl})
                                 (and thus the printer driver), look for variable {\tt \${}prmsel} in these files.\\
 \param{3rd}    & \novar        & Empty.\\
 \param{4th}    & \tt prtcmd(1) & If the \param{2nd} is set to {\tt vstcommands}, file {\tt prt{\UL}dvips.tcl} is 
                                 prepared to evaluate and execute up to 4 commands specified in this setting file
                                 in variables {\tt prtcmd(1)} \ldots{} {\tt prtcmd(4)}.
                                 Before execution of a program (by means of {\tt mkCmd{\UL}wait}, 
                                 \sRef{ProgramExecFiles}), the option string is evaluated and the following variables 
                                 are replaced by the current values:\\
                &               & {\tt \${}mainfile} (main file name without file suffix),\\
                &               & {\tt \${}prt{\UL}file} (print file name, to be submitted to the printer),\\
                &               & {\tt \${}opt1} (printer driver options 
                                 (e.g.\ {}offset), except format specific options),\\
                &               & {\tt \${}opt2} (format specific options for the printer driver).\\
 \param{5th}    & \tt prtcmd(2) & See \param{4th}.\\
 \param{6th}    & \tt prtcmd(3) & See \param{4th}.\\
 \param{7th}    & \tt prtcmd(4) & See \param{4th}.\\
\end{vstfmt}
\DefLine{2nd}

Each of these printer driver setting files interacts with a Tcl/Tk procedure in the corresponding source code file
{\tt prt{\UL}dvi\It{xxx}.tcl} (\sRefs{AddingPrinterDriver} and~\ref{ProgramExecFiles}).

Up to now the following printer drivers have been prepared in \xtem, all having the same structure as given in this
section (for adding other printer drivers \sRef{AddingPrinterDriver}):


\newcommand{\PD}[1]{\tt prt{\UL}#1.vst&\tt prt{\UL}#1.tcl&{\tt#1} printer driver\\}
\begin{tabular}{llll} \PD{dvips} \PD{dvilj} \PD{dvijep} \end{tabular}

In {\tt prt{\UL}dvips.vst} we defined entries using {\tt dvidvi}, 
this `non-standard' program you can get from our ftp server: \einr\ftpiwdtex dvidvi-1.1.tar.gz



\vstfile{1}{spellcheck.vst}{Spell Check}{List of spell check programs}\label{spellcheck.vst}

\FALines
\begin{vstfmt}
                &               & Text (\nnnch{80}).\\
 \param{1st}    & \tt spcmd     & Name of the spell check program.\\
 \param{2nd}    & \tt splang    & Language: may be used to select the dictionary when calling the spell check program.\\
 \param{3rd}    & \tt spcorr    & {\tt K} : the spell check program possibly changes the text file.\\
                &               & \Empty{} : otherwise.\\
 \param{4th}    & \novar        & \Empty.\\
 \param{5th}    & \tt spoptions & Option string for the spell check program.\\
\end{vstfmt}
\DefLine{2nd}

In \param{5nd} ({\tt spoptions}) you can use variable {\tt \${}mainfile}
(e.g.\ {}in order to use a dictionary specific for the main file to be \TeX'ed).

If the spell check program is marked to possibly change the text files (variable {\tt spcorr}), 
and an editor is active at the same time, there may be conflicts. 
In this case, the user is given a warning before starting the spell check program.

\ButSup{b{\UL}spell}


\vstfile{1}{suffix.vst}{File Suffixes}%
 {List of suffixes for ``files to edit'' (file selection menu), 
  see also file {\tt texsuffix.vst} (\Ref{texsuffix.vst})}\label{suffix.vst}

All lines:\\
\begin{vstfmt}
 columns 1-end  & \tt esuff     & Suffix ( {\tt * |~.tex |~.aux | }\ldots{} )
\end{vstfmt}




\vstfile{1}{syntax.vst}{\LaTeX{} Syntax Check}{List of syntax check programs}\label{syntax.vst}

\FALines
\begin{vstfmt}
                & \tt sytext    & Text (\nnnch{55}).\\
 \param{1st}    & \tt syntax    & Name (call) of the syntax check program.\\
 \param{2nd}    & \tt syoptions & Option string for the syntax check program.\\
\end{vstfmt}
\DefLine{2nd}

\ButSup{b{\UL}syntax}

In {\tt syntax.vst} we defined entries using {\tt texchk}, 
this `non-standard' program you can get from our ftp server: \einr\ftpiwdtex texchk.tar.gz



\vstfile{1}{texfmt.vst}{\TeX{} Formats}{List of \TeX{} formats}\label{texfmt.vst}

\FALines
{\hfuzz10pt
\begin{vstfmt}
                &               & Text (\nnnch{20}).\\
 \param{1st}    & \tt texfmt    & \TeX{} format ( {\tt tex | latex | slitex | }\ldots{} 
                                 = shell script/command name for \TeX{} call).\\
 \param{2nd}    & \tt quickenable       & \tt 0 | 1\\
                &                       & {\tt 0} : ``\quickdirty'' button disabled,\\
                &                       & {\tt 1} : ``\quickdirty'' button enabled with this \TeX{} format.\\
 \param{3rd}    & \tt quickverbatim     & \tt 0 | 1\\
                &                       & {\tt 1} : preamble and ``mouse-grab'' are to be be added (in verbatim mode)
                                         at the end; available for \LaTeX format only: \param{5th} must be set to 
                                         {\tt latex}).\\
                &                       & {\tt 0} : otherwise.\\
 \param{4th}    & \tt quickprereq       & \tt 0 | 1\\
                &                       & {\tt 0} : preamble not requested for this \TeX{} format (e.g.\ {}\TeX).\\
                &                       & {\tt 1} : preamble requested for this \TeX{} format (e.g.\ {}\LaTeX).\\
 \param{5th}    & \tt quickpreform      & Specifies the \TeX{} format for ``\quickdirty'' (passed to file quick.tcl),
                                         see \param{3rd}.\\
 \param{6th}    & \tt quicksuffix       & Suffix for the ``\quickdirty'' \TeX{} file.\\
 \param{7th}    & \tt quickpreamble     & Preamble for this \TeX{} format (used only if there is no main file name
                                        selected, otherwise the preamble is extracted from the main file).\\
 \param{8th}    & \tt quickendpre       & This string ends the preamble, the main file is scanned exactly 
                                         for this string.\\
 \param{9th}    & \tt quickenddoc       & This string is added to the ``mouse grab'' at the end of the file.\\
 \param{10th}   & \tt mainfilgrep       & List of search strings (each element included in braces "`\BrL{}\ldots\}"')
                                         in order to get the option to reduce the list in the main file selection box.\\
\end{vstfmt}
\DefLine{2nd}
}



\vstfile{1}{texopts.vst}{Options for TeX{} run}%
  {This list specifies whether to analyse the transcript (logfile) after a \TeX{} run
  and to produce tags for each error for quick error correction}\label{loganalyze.vst}

\FALines
\begin{vstfmt}
                & \tt texopttext        & Text (\nnnch{24}).\\
 \param{1st}    & \tt texopts           & Options for \TeX{} run (e.g.\ {}to force nonstop mode
                                         to get all errors in run without interaction).\\
\end{vstfmt}
\DefLine{2nd}



\vstfile{1}{texsiz.vst}{\TeX{} Program Size}{List of prefixes: size of \TeX{} programs}\label{texsiz.vst}

\FALines
\begin{vstfmt}
                & \tt texmtext  & Text (\nnnch{20}).\\
 \param{1st}    & \tt texmem    & Prefix for \TeX{} program call (normally left blank or {\tt big} otherwise).\\
\end{vstfmt}
\DefLine{2nd}



\vstfile{1}{texsuffix.vst}{\TeX{} File Suffixes}%
 {List of suffixes for \TeX{} files/main files (file selection menu), also used for ``additional  
  programs''; see also file {\tt suffix.vst} (\Ref{suffix.vst})}\label{texsuffix.vst}

All lines:\\
\begin{vstfmt}
 columns 1-end  & \tt texsuffix & Suffix ( {\tt.tex |~.ltx |~.doc | }\ldots{} ).
\end{vstfmt}



\vstfile{1}{utility.vst}{Additional Programs (Utilities)}{List of additional programs}\label{utility.vst}

\FALines
\hspace*{0.7em}\begin{tabular}{llp{13.0cm}}
                &               & Text (\nnnch{50})\footnotemark.\\
 \param{1st}    & \novar        & Command name (may be followed by `\&': command execution in the background).\\
 \param{2nd}    & \novar        & Option string for this command.\\
 \param{3rd}    & \novar        & {\tt file | nofile | optfile} : optional parameter, 
                                 specifies whether the program (\param{1st}) needs a file or not:\\
                &               & {\tt file} : a file must be selected before execution (default),\\
                &               & {\tt nofile} : no file name is allowed at call 
                                 (file name will be ignored if selected),\\
                &               & {\tt optfile} : file name is optional.\\
 \param{4th}    & \novar        & Default suffix for the file list (\param{5th});
                                 this value is used to fill the file list after program selection.\\
 \param{5th}    & \novar        & Suffix list for the suffix/file selection box.\\
                &               & If the 4th/5th parameter are empty, the suffix list is taken from 
                                 file {\tt texsuffix.vst} (\sRef{texsuffix.vst}).\\
 \param{6th}    & \novar        & Name of an (existing) directory\sameaslastfootnote.\\
                &               & The command is executed in this directory---the switching to this directory is
                                 temporarily; if this parameter is specified (non-empty), the command should be executed 
                                 in the background (\param{1st} followed by `\&').\\
 \param{7th}    & \novar        & {\tt nobackup} | {\tt backup} | empty (same as {\tt backup});\\
                &               & this parameter specifies, whether a backup of the input file is to be created or not.\\
\end{tabular}

\footnotetext{This text/parameter may contain the `main file name' and the
                                 `edit file name', i.e.\ {}the \xtem{} variables {\tt\${}main{\UL}file} and 
                                 {\tt\${}efile}, look at the examples in file {\tt utility.vst}}
\ButSup{b{\UL}additional}



{\hfuzz10pt
\subsection{User Preferences: {\normalsize\tt HOME/.xtem{\UL}\lang.vst, \fnam{\UL}\lang.vst {\rm and}~.lastxtem}}%
        \label{.xtem.vst}
}

These files are generated by \xtem{} in the user's area (click at \Button{save preferences} in the main menu);
by this the user can save his current settings.

Each line of the two {\tt.vst} files contains the name of a variable, separated by at least one blank
from the value assigned to this variable.

In the following only those variables not specified in \Ref{SettingFiles} are listed:
 
\hspace*{0.7em}\begin{tabular}{lp{\vv}}
 variable name  &  variable value\\
\hline
 \tt prpreopt   & Option string for the dvips run, if such a run is necessary
                 before a preview start (necessary before ghostview e.g.).\\
 \tt prformat   & Currently selected format for the preview program.\\
 \tt prtformat  & Currently selected format for printing; usually {\tt prformat} and {\tt prtformat} will 
                 automatically have the same values (if possible, i.e.\ {}the selected value for the one is also 
                 available for the other, otherwise the user will be advised!).\\
 \tt prtselstr  & String, containing all selection criteria to identify a printer setting.\\
 \tt prtpresel  & String, containing asterisks ``*'' or the specified criteria for printer list reduction.\\
 \tt hlp{\UL}bmsuppr& \tt 0 | 1\\
                & {\tt 0} : bitmaps are suppressed by default in \LATeX{} syntax help.\\
                & {\tt 1} : bitmaps are displayed by default in \LATeX{} syntax help.\\
\end{tabular}

\medskip
At start of \xtem{} or when you click at the \Button{load preferences}, {\tt\fnam{\UL}\lang.vst} is read---where
\fnam{} stands for the main-file name ({\tt.tex}-file which will be used when \TeX{} is called). 

If it's not found, then file {\tt HOME/.xtem{\UL}\lang.vst} is read instead.
If this file isn't found likewise, the default values are taken from the
files {\tt\XtP/xtem{\UL}path/locals{\UL}*/*.vst} (\sRef{Installation}).

\smallskip
{\tt.lastxtem} contains file names (main-file name and edit-file name) at the moment of last `save'.
If no file name is specified at \xtem{} start (\sRef{RunXtem}) and this file exists,
the file names of {\tt.lastxtem} are used.



\section{Adding a new Printer Driver}\label{AddingPrinterDriver}


For each \It{new} printer driver (\sRef{printing.vst}, 3rd parameter) added to file
{\tt printing.vst}---its name being represented by {\tt dvi\em xxx} in the following---you have to create two files:

\begin{tabular}{ll}
 file name                                      & in analogy e.g.\ {}to file\\
 \hline
 \tt\XtP/prt{\UL}dvi\It{xxx}.tcl                        & \tt prt{\UL}dvips.tcl\\
 \tt\XtP/locals{\UL}\lang/prt{\UL}dvi\It{xxx}.vst       & \tt prt{\UL}dvips.vst\\
\end{tabular}

(i.e.\ {}the printer driver {\tt dvips} may serve as a model).

The name of the new procedure name must be added to the file {\tt\XtP/tclIndex} too.



\section{Installing the `\quickdirty' Facility}\label{quickdirty}

The installation of the \quickdirty{} facility depends on 2 setting files (\sRefs{install.vst} and \ref{texfmt.vst}):\\
{\tt\begin{tabular}{ll}
        \rm file name   & \rm variables\\
        \hline
        install.vst     & quickdelfile quickfile quickmultprv quicknonstop quickprev\\
                        & quickprevstd quickprsstd\\
        texfmt.vst      & quickenable quickverbatim quickprereq quickpreform quicksuffix\\
                        & quickpreamble quickendpre quickenddoc
 \end{tabular}}

If you install \xtem{} first, i.e.\ if there are no setting files from previous installations, normally \quickdirty{}
will work fine after running the installation procedure, i.e.\ {}the \quickdirty{} button will be active, as the defaults
for the variables you can specify in file {\tt install.vst} are set properly.

Yet, if there are setting files from some previous \xtem{} installation (\xtem{} version 5 or even older), please
check up file {\tt INSTPATH/locals{\UL}\It{language}/texfmt.vst} (compare with file 
{\tt INSTPATH/locals{\UL}\It{language}.LRW/texfmt.vst}, copy \ldots{\tt .LRW/texfmt.vst} to \ldots{\tt /texfmt.vst}).
After this, if the \quickdirty{} button isn't active,
select the \TeX/\LaTeX{} format in the \TeX{} setting menu once more or `reset to defaults' 
(look for `\quickdirty: enabled' when displaying the current settings).
After this the \quickdirty{} button  in the main menu should be active;
don't forget to save the settings as `personal settings'.



\section{Installing the `Main File Selection' Facility}\label{mainfilelistreduction}

In a similar way the installation of the facility to reduce the file list displayed in the main file selection box in the
file selection menu to files having a \verb|\documentclass| or \verb|\documentstyle| command depends on 2 setting files
(\sRefs{install.vst} and \ref{texfmt.vst}):\\
{\tt\begin{tabular}{ll}
        \rm file name   & \rm variables\\
        \hline
        install.vst     & mdispmain mdispmainv\\
        texfmt.vst      & mainfilgrep\\
 \end{tabular}}

If there are no setting files from previous installations at the moment when you install \xtem{} normally this facility
will work fine after running the installation procedure, i.e.\ {}in the file selection menu radiobuttons to reduce
the main file selection box are generated, as the defaults for the variables you can specify in file {\tt install.vst}
are set properly.

Yet, if there are setting files from some previous \xtem{} installation (\xtem{} version 5 or even older), please
check up file {\tt INSTPATH/locals{\UL}\It{language}/texfmt.vst} (compare with file 
{\tt INSTPATH/locals{\UL}\It{language}.LRW/texfmt.vst}, copy \ldots{\tt .LRW/texfmt.vst} to \ldots{\tt /texfmt.vst}).
After this, if the radiobuttons `all' and `main files only' aren't present above the main file selection box,
select the \TeX/\LaTeX{} format in the \TeX{} setting menu once more or `reset to defaults' 
(look for `string(s) for main file list reduction: \ldots' when displaying the current settings).
After this the radiobuttons in the file selection menu should be generated;
don't forget to save the settings as `personal settings'.



\section{How to set Fonts and Colours}\label{Fonts}

In \Ref{install.vst} the setting of variables---including font variables---is specified.
Yet there may be problems if \xtem{} is installed in a network of computers/X-terminals, 
and if fonts known to a computer/X-terminal are not known to another. 
Thus the user may set the environment variable {\tt XTEMINSTALL} to the name of a file which contains 
his ``{\tt install.vst}''.
If an environment variable {\tt XTEMINSTALL} is set, the variables described in \Ref{install.vst} 
are read from the file specified in {\tt XTEMINSTALL} instead from file {\tt\XtllP/install.vst}.

And there is an alternative to set fonts: after scanning file {\tt\XtllP/install.vst}, \xtem{} scans
{\tt.Xdefaults} (or any other file specified by the environment variable {\tt XTEMXDEFAULTS}) for
\xtem{} font specifications. By this some or all fonts specified in {\tt install.vst} can be overwritten.

In the following we give examples for font specifications in {\tt.Xdefaults}
(you may use the Unix program {\tt xfontsel} for a lookup for fonts installed at your platform;
the fonts (at least if you use {\tt german} as language setting) should include the German-umlaute):\\
{\footnotesize\tt
\begin{tabular}{ll}
xtem*font: & -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1\\
xtem*Text.font: & -*-lucidatypewriter-medium-r-normal-sans-17-*-100-100-m-*-iso8859-1\\
xtem*font.error.font: & -adobe-courier-bold-r-normal--*-120-*-*-*-*-*-*\\
xtem*Listbox.font: & -adobe-courier-medium-r-normal--*-120-*-*-*-*-iso8859-1\\
xtem.printpresel*Listbox.font: & -adobe-courier-medium-r-normal--*-120-*-*-*-*-iso8859-1\\
xtem.printpresel*Radiobutton.font: & -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1\\
xtem.printpresel*selected.font: & -adobe-helvetica-bold-r-normal--*-120-*-*-*-*-iso8859-1\\
xtem*font.errortag.font: & -*-lucidatypewriter-medium-r-normal-sans-14-*-100-100-m-*-iso8859-1\\
xtem.erroredit*Text.font: & -*-lucidatypewriter-medium-r-normal-sans-17-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.normal.font: & -*-new century schoolbook-medium-r-normal-*-120-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.tag.font: & -*-new century schoolbook-medium-r-normal-*-120-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.bold.font: & -*-new century schoolbook-bold-r-normal-*-120-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.boldlrge.font: & -*-new century schoolbook-bold-r-normal-*-140-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.teletype.font: & -*-lucidatypewriter-medium-r-normal-sans-17-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.telelrge.font: & -*-lucidatypewriter-medium-r-normal-sans-20-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.telesmll.font: & -*-lucidatypewriter-medium-r-normal-sans-14-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.italic.font: & -*-new century schoolbook-medium-i-normal-*-120-*-*-*-*-iso8859-1
\end{tabular}
}

or---if you have excellent eyes and a small screen:\\
{\footnotesize\tt
\begin{tabular}{ll}
xtem*font: & -adobe-helvetica-bold-r-normal--*-80-*-*-*-*-iso8859-1\\
xtem*Text.font: & -*-lucidatypewriter-medium-r-normal-sans-11-*-100-100-m-*-iso8859-1\\
xtem*font.error.font: & -adobe-courier-bold-r-normal--*-80-*-*-*-*-*-*\\
xtem*Listbox.font: & -adobe-courier-medium-r-normal--*-80-*-*-*-*-iso8859-1\\
xtem.printpresel*Listbox.font: & -adobe-courier-medium-r-normal--*-80-*-*-*-*-iso8859-1\\
xtem.printpresel*Radiobutton.font: & -adobe-helvetica-bold-r-normal--*-80-*-*-*-*-iso8859-1\\
xtem.printpresel*selected.font: & -adobe-helvetica-bold-r-normal--*-80-*-*-*-*-iso8859-1\\
xtem*font.errortag.font: & -*-lucidatypewriter-medium-r-normal-sans-11-*-100-100-m-*-iso8859-1\\
xtem.erroredit*Text.font: & -*-lucidatypewriter-medium-r-normal-sans-11-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.normal.font: & -*-new century schoolbook-medium-r-normal-*-100-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.tag.font: & -*-new century schoolbook-medium-r-normal-*-100-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.bold.font: & -*-new century schoolbook-bold-r-normal-*-100-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.boldlrge.font: & -*-new century schoolbook-bold-r-normal-*-120-*-*-*-*-iso8859-1\\
xtem.syntaxhelp.teletype.font: & -*-lucidatypewriter-medium-r-normal-sans-14-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.telelrge.font: & -*-lucidatypewriter-medium-r-normal-sans-17-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.telesmll.font: & -*-lucidatypewriter-medium-r-normal-sans-11-*-100-100-m-*-iso8859-1\\
xtem.syntaxhelp.italic.font: & -*-new century schoolbook-medium-i-normal-*-100-*-*-*-*-iso8859-1
\end{tabular}
}
\pagebreak[1]

In a similar way you can set colours:\\
{\footnotesize\tt
\begin{tabular}{ll}
xtem*background: & black\\
xtem*foreground: & white\\
xtem*activeBackground: & green\\
xtem*activeForeground: & sienna\\
xtem*disabledForeground: & yellow\\
xtem*highlightColor: & red\\
xtem*highlightBackground: & DarkGreen\\
xtem*insertBackground: & MidnightBlue\\
xtem*selectBackground: & azure\\
xtem*selectColor:  & cyan\\
xtem*selectForeground: & blue\\
xtem*troughColor: & magenta\\
xtem.erroredit.error.background: & green\\
xtem.erroredit.error.foreground: & yellow\\
xtem*Text.Background: & LightCyan1\\
xtem*Text.Background: & Gray 98\\
xtem*Listbox.Background: & Gray95\\
xtem*Button.Background: & LightCyan1\\
xtem*Radiobutton.Background: & LightCyan1\\
\end{tabular}
}
\pagebreak[1]

Yet we doubt that you like these odd settings---they are for demonstration of the effects only.
And these setting are not used for a second call of \xtem{} (in parallel to an existing \xtem{} menu);
for such parallel existing menus you have (at the moment) to add additional sets using 
\xtem1, \xtem2, \ldots instead of \xtem.


\section{Known Problems}\label{KnownProblems}

\begin{mlist}
\Item{Call of a non-existing program:} can only happen if the local administrator has not installed all programs 
        listed in the setting files etc.\ {}(\sRefs{SettingFiles} and \Ref{ProgramList}).\par
        a) if a non-existing program was called by means of {\tt mkCmd{\UL}wait} (\sRef{ProgramExecFiles})
        and variable {\tt whichcheck} (\sRef{install.vst}) is set to {\tt no}, this results in an X11 error message:
        `\ldots{\tt X Error of failed request}\ldots';
        if {\tt whichcheck} is set to {\tt yes}, you will get a qualified message\par
        b) if a non-existing program was called in the background by means of '{\tt catch "exec \ldots"}',
        the resulting error message will be written in the xterm window (\sRef{ProgramExecFiles}).\par
        If you click at \Button{exec mode} in the main menu of xtem and then select {\tt mkcommand.0},
        you may see what should be called via {\tt mkCmd{\UL}wait} (\sRef{mkcommand})!
\pagebreak[2]
\Item{Error pop-up: can't read ``tkPriv(x)'': no such element in array.}~\\
        (occasionally and Tcl version $<$ 8.0 only?):\par
        Sometimes after middle mouse click in entry widgets and  no mouse grab done before: seems to be
        a missing initialisation in Tk; click at `OK'.
\end{mlist}

\bigskip
We heard of the following problems arising at the installation of \xtem{} on different systems:

\begin{mlist}
\Item{All systems:} ``Wrong characters'' in the \LATeX{} syntax menu; this is caused by unsuitable fonts, e.g.\
        {\tt telelrge: -*-Terminal-Medium-R-Normal-*-140-*} should be replaced in file {\tt install.vst} 
        (\sRef{install.vst})
\Item{All systems:} Problems with {\tt mkcommand.4}; most of these problems are either caused by:\par
        a) Variable {\tt xtermcall} in file {\tt install.vst} (normally set to {\tt xterm}, but your installation 
        may need another value such as {\tt aixterm}, \sRefs{mkcommand} and~\ref{install.vst}).\par
        b) ``send'' not allowed by X-Server caused by the security mechanism (\sRef{mkcommand}: {\tt mkcommand.4}).
\Item{AIX (version~?):} The right mouse button doesn't give help texts, 
        instead of this a menu: `Restore', `Move',\ldots{} comes up.
        Error cause: in file {\tt system.mwmrc} (in {\tt /usr/lib/X11/} or {\tt /usr/lpp/X11/lib/X11/})
        there exists a binding `{\tt Buttons <Btn3Down> \ldots{} window}'.
\Item{AIX (version~?):} Use {\tt aixterm} instead of {\tt xterm} in the setting files (\sRef{SettingFiles}), 
        especially for calling TEN/PLUS editor (\sRefs{editor.vst} and~\ref{install.vst}).
\Item{Sun SOLARIS2.x:} Be sure that BSD commands cannot be found during the installation of Tcl/Tk 
        (variable {\tt PATH} must not include {\tt/usr/ucb})!
\Item{HP 9000:} {\tt Error in tcl script: / Error: illegal last Unit -1 / \ldots} at \xtem{} call;
        these messages seem to have no further effect. This error was reported from some few installations.
        We know from at least 2 correct installations, thus this seems to depend on the system version or on the
        installation of Tcl/Tk.
\end{mlist}




\section{``Hotline''}\label{Hotline}

If nothing else helps, don't hesitate to contact us:

\begin{vstfmt}
 questions concerning                   & contact\\
 \hline
 \xtem                                  & \xtememail,  phone. +421 - 218 - 3532\\
 installation of Tk, Tcl                & \tt lotz@\iwdinternet\\
\end{vstfmt}
\pagebreak[1] 




\section{Please don't forget: Installation Report}\label{InstallationReport}

If you like (or don't like) this program, \It{please} drop me a line.
I would like to hear how the program works (or doesn't work) for you.
I won't know what new features to add if I don't get any feedback. Thanks!

{\bf In any case after successful installation, especially on a system not mentioned before in \Ref{mkcommand}, 
please send an e-mail} to \xtememail{} with answers to some or all of the following questions
(and also mail us all typographical/linguistic errors you noticed!):

{\tt
\medskip
institution:\\
address:\\
name:\\
phone:\\
e-mail:

computer:\\
system-version:

xtem-version:\\
mkcommand-version used normally:\\
more mkcommand-versions which run correctly (if tested): \\
mkcommand-versions which don't run correctly (if tested): 

Tcl-version:\\
Tk-version:

problems which happened:

hints for further improvements:

if you want to get an e-mail when future versions of xtem will be released,\\
please give e-mail address(es) here:
}

\medskip
You will find a copy of this list in file {\tt Installation.Reply}


\section{Announcements of New Releases and \xtem{} Discussion List}\label{Announcings}

If you want to get an e-mail when new versions of \xtem{} will be released, please send an e-mail to:\\
  \einr{\tt\xtememail}\\
with subject (or body):\\
  \einr{\tt xtem: new release information}

There is also a list to discuss new features of \xtem; you can subscribe this list by mailing to:\\
  \einr{\tt\majordomo}\\
with body:\\
   \einr{\tt subscribe xtem-list}\\
   \einr{\tt end}

\end{document}%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
\endinput%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
