Copyright (C) 1994  G. Lamprecht, W. Lotz, R. Weibezahn; LRW c/o Uni Bremen

The program xtem may be used and copied under the conditions of the
(added) GNU GENERAL PUBLIC LICENSE,
the Copyright must not be deleted or modified.

IN NO EVENT SHALL THE LRW 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 LRW
HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

THE LRW 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 LRW NO OBLIGATION TO
PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.

You may get xtem  directly from the authors 
   (anonymous, password: RFC-conform e-mail address):
   ftp.lrw.uni-bremen.de  pub/tex/xtem/xtem_texmenu.3.xx.tar.gz
                          pub/tex/xtem/xtem_texmenu.README
                          pub/tex/xtem/xtem_texmenu_eng.ps.gz
                          pub/tex/xtem/xtem_texmenu_ger.ps.gz
                                                      xx = patch level, e.g. 05


For a successfull installation you need:
 
-  Unix
-  C compiler for the installation of Tcl, Tk, TclX (e.g.  gcc compiler)
   (version of Tcl/Tk see below!)
-  X11      R4 or R5
-  3-button mouse
 
You may get Tcl/Tk/TclX 
a) directly from:
 - Tcl      Vers. 7.3   ftp.cs.berkeley.edu   ucb/tcl/tcl7.3.tar.Z    
 - Tk       Vers. 3.6   ftp.cs.berkeley.edu   ucb/tcl/tk3.6.tar.Z 
 - TclX     Vers. 7.3a  ftp.neosoft.com       pub/tcl/distrib/tclX7.3a.tar.gz
 - addinput             ftp.neosoft.com       pub/tcl/distrib/addinput-3.6a.gz
b) or alternatively e.g. from:
 -                   harbor.ecn.purdue.edu    pub/tcl/code  pub/tcl/extensions
 -                   ftp.lrw.uni-bremen.de    pub/tcl

You need
 - Tcl at least version 7.0, better version 7.3 
   (this version of xtem does not work with Tcl version 7.4 
    because of incompatiblities in the corresponding versions 
    of Tk; look for future releases of xtem or contact us),
 - corresponding version of Tk and
 - corresponding version of TclX (extended Tcl),
 - corresponding version of addinput --- is not absolutely necessary, but
   recommended for some Unix systems (see below: section IV "mkcommand")
   for reasons of performance (reduced system overhead, enhanced program 
   execution).



The installation of Tcl, Tk, TclX and addinput was without problems
(Sun SPARC running SOLARIS 2.3) by means of the "Makefile", "Configure" and
"patch"; patch P1 must be applied to Tk
(Patch P1 to Tk version 3.6, otherwise see README.SIGSEGV).

We used Gnu gcc, version 2.5.8 as C compiler.

The executable programs produced by this way:
 tclsh (Tcl), wish (Tcl incl. Tk), tcl (extended Tcl), wishx (ext. Tcl incl. Tk)
occupied 
  ca. 600 KB    in the version without "shared libraries",
  ca.   4 KB    in the version with "shared libraries"

The version "with shared libraries" we could only produce after
a correction at the makefile. This correction is available from:
   harbor.ecn.purdue.edu    pub/tcl/extensions/tcltk_shlib0.4.tar.gz
or from us:
   ftp.lrw.uni-bremen.de    pub/tcl/patches
The version "with shared libraries" works excellent at our installation.


If on your computer Tcl is installed, but TclX (extended Tcl) is not installed,
you may test xtem and become acquainted with it:
all the menus work except the execution of programs, which are started
by means of mkCmd (TeX, syntax check etc.). 
Apart from this and except the process administration, the menu
acts just like the full Tcl/Tk/TclX installation.
(TclX is used only for the "runs", that means for the execution of programs.)


With older versions of Tcl (older than Tcl version 7.3) you may loose
file descriptors. Yet this is no severe error -- it happens seldom;
if it happens, then the effect is, that you cannot start any more process
(e.g. TeX run). Then you have to leave xtem and call xtem once more.

The version of xtem and the version of Tcl you may see by
left mouse click on the "help button" in the main menu of xtem.
 

 
Hints for Implementators:
========================= 

0. Multilingual xtem:
---------------------

  xtem is multilingual; up to now we have prepared an English and a German
  version. 
  Other languages may easily be added, only pure text files (dictionaries)
  must be translated and the shell script "xtem" must be completed. 
  For each language there are two directories named 
    .../xtem/help_xxx/ (with subdirectories)       and 
    .../xtem/locals_xxx/,
  where xxx stand for the language.
  If you want to translate these text files, please let us know, as we would
  like to include further languages.
  In this README we use the English texts when we refer to buttons,
  thus we recommend to call the English version during the first test
  (call:  xtem -l english [filename] ).

  You will find the language dependent texts in the files
      .../xtem/help_*/button.texts 
  each text is assigned to a variable; e.g. in
      .../xtem/help_english*/button.texts 
  you will find the following line
      c2al                file list
  By this the text "file list" is assigned to variable vv(c2al).
  In the files mentioned below array vv(...) is used
  in order to keep the source files language independent.

  We thank Katherine Wipf for the careful proofreading of the English texts
  (new errors may be introduced by ourselves in the course of updates!)


I. Character Set:
-----------------

   We use "German umlaute" (in the German version of xtem)
   according to the  8 bit code
                "DIN 66303-ARV8 (Allgemeine Referenz-Version des 8-Bit-Code)"
                "ISO 8859-1"
                if necessary you may recode e.g. ISO2IBM:
   tr '\304\326\334\337\344\366\374' '\216\231\232\341\204\224\201'
        Ae  Oe  Ue  ss  ae  oe  ue  

 
II. Directories and Files:
--------------------------
 
                   |---/help_english/*.hlp
                   |                /button.texts
                   |                /latex/*
                   |                /miscellaneous/*
                   |---/locals_english/*.vst
                   |
                   |---/help_german/*.hlp
                   |               /button.texts
                   |               /latex/*
                   |               /miscellaneous/*
        .../xtem---|---/locals_german/*.vst
                   |
                   |
                   |   (---/help_xxx/*                                   )
                   |   (---/locals_xxx/*                                 )
                   |   (        where xxx stands for a language;         )
                   |   (        eventually further languages may be added)
                   |
                   |
                   |---*.tcl
                       tclIndex
                       tclIndex.7.0
                       mkcommand.*
                       README
                       xtem_*
                       xtem             <-- this is the shell script
                                            to start xtem execution

                                                 
   call:  xtem [ -l language ] [ filename[.suffix] ]
                       |                     |
                       "german"              ".tex"
                       "deutsch"             ".ltx"
                       "english"

   language specific directories may be deleted, if you don't want to use
   this language.
   For example delete  .../xtem/locals_german   and   .../xtem/help_german
   if you don't want to use the german version (this will save about 1.2MB),
   or delete  .../xtem/locals_english   and   .../xtem/help_english
   if you don't want to use the english version (this will save about 1.2MB);
   in any case you should modify the shell script  xtem  (see above)


III. Permissions:
-----------------

        chmod go-w xtem xtem/* xtem/*/* xtem/*/*/*
        chmod a+r  xtem xtem/* xtem/*/* xtem/*/*/*
        chmod a+rx xtem
        chmod a+rx xtem/xtem xtem/xtem.tcl xtem/xtem_* xtem/locals_*
        chmod a+rx xtem/help_* xtem/help_*/latex xtem/help_*/miscellaneous


IV. Install your mkcommand:
---------------------------

  In the file      .../xtem/locals_*/default.vst
  there must be a line "mkcommand          mkcommand.?"
                                                     ^
                                                     |
                                                     +--- numeral 0 ... 5
  (e.g. "mkcommand          mkcommand.5").
  By this you select and load one of the files mkcommand.?
  with all the procedures in it. These procedures realize the execution
  of programs like "tex", "dvips" etc., which normally are called via the
  command "mkCmd_wait" in xtem shell script (see below).

  We have prepared different versions of these procedures.
  Not all of them fit to all systems. In the following we give a short
  description of the versions 0 to 5:

  ****************************************************************************
  * we are very interested in getting response from  NetBSD  implementations *
  ****************************************************************************

  a) 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.
     needs:     Tcl, Tk
     runs with: all systems
     *** please inform us in case of differences to these "release notes"
      
      
  b) mkcommand.1

     Full functionality, reading from Unix is done character by character,
     output is written into the text message widget of xtem in blocks.
     Missing functionality of BSD-systems is taken into account,
     this may lead to performance loss, when the protocol text of the
     program is very large.

     needs:     Tcl, Tk, TclX    
     runs with: all systems 
     tested: SunOS4, SGI INDIGO, SGI Irix 5.3, DEC Ultrix 4.3a, Linux, 
             Apollo Domain OS/Unix HP9000/400, HP-UX HP9000/700
     *** please inform us in case of differences to these "release notes"
      

  c) mkcommand.2

     Full functionality, reading from Unix is done in blocks,
     output is written into the text message widget of xtem in blocks.
     Good performance, does not run with BSD based Unix.
      
     needs:     Tcl, Tk, TclX    
     runs with: SYSVR4-Unix 
     tested: Sun_SOLARIS2.3, AIX3.2.5, Linux, Apollo Domain OS/Unix HP9000/400,
             SGI Irix 5.3
     runs not with: HP-UX HP9000/700
     *** please inform us in case of differences to these "release notes"
      
      
  d) mkcommand.3

     Full functionality, reading from Unix is done in blocks,
     output is written into the text message widget of xtem in blocks.
     High performance, does not run with BSD based Unix.
      
     needs:     Tcl, Tk, TclX, addinput   
     runs with: SYSVR4-Unix 
     tested: Sun_SOLARIS2.3, AIX3.2.5, Linux, Apollo Domain OS/Unix HP9000/400,
             SGI Irix 5.3
     runs not with: HP-UX HP9000/700 (not complete SYSV functionality!)
     *** please inform us in case of differences to these "release notes"
      

  e) mkcommand.4

     Full functionality, generates an xterm window and Tk-send-commands.
     Still under development (runs with a maximum of performance with
     --- at least we hope --- all systems)

     needs:     Tcl, Tk, TclX,
                X-Server with  a) "xauth-style authorization"
                         or    b) Tk compiled with "-DNO_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.
     runs with: most Unix systems 
     tested: Sun_SOLARIS2.3, Apollo Domain OS/Unix HP9000/400,
             HP-UX HP9000/700 with minor restrictions,
             SGI Irix 5.3 with minor restrictions
     runs not with: Linux
     *** please inform us in case of differences to these "release notes"


  f) mkcommand.5

     Full functionality, 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
     xtem_prog by the local administrator.)

     needs:     Tcl, Tk, TclX
     runs with: all systems 
     tested: Sun_SOLARIS2.3, Apollo Domain HP9000/400, HP-UX HP9000/700,
             SGI Irix 5.3
     *** please inform us in case of differences to these "release notes"


  This means you first have to test the different versions of mkcommand.?
  on your system.
  Then you have to remove all versions which don't work properly with
  your system from the file /locals_*/mkcommand.vst (see below): remove the 
  corresponding lines.
  Put down the default value you want for the mkcommand version in the
  file /locals_*/default.vst
  If it works properly with your system, we recommend version 3 (mkcommand.3).



V. Check and modify all the following Setting Files:
----------------------------------------------------

  xtem.tcl   a) line 1: the window shell including Tcl/Tk/TclX must be specified
                        here; e.g.
                                   #!/usr/local/bin/wishx -f
             b) up to "end changes by the local administrator":
                  specify the path to the directory xtem; e.g. 
                                   set xtem_path "/usr/local/lib/tex/xtem"

  xtem       shell script to call xtem.tcl must be modified:
             - select your default language (up to now: "english" or "german"):
               edit file "xtem" and make active one of the settings
               for the variable "defaultlanguage"
             - if necessary another window shell and other path names must be
               specified!


  The following files mostly contain selection lists for programs together with
  specifications like option strings (e.g. preview.vst), suffixes for file 
  selection (e.g. editor.vst), TeX formats (e.g. texfmt.vst) etc.

  They must be adapted to the local situation by the local Tex administrator.

  If necessary, each institute/department (or every single user)
  may have its own complete set of setting files and customize it.
  For this there is the environment variable XTEMVSTDIR:
  if this environment variable exists, its value must be the qualified path 
  name to a directory. A .vst file is searched first in this directory,
  if it is not found, the file contents from the directory /xtem/locals-*/
  is taken.


  First a remark to the structure of the following files (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 "field separator" for this file,
  that means the parameters in the following lines must by 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. The number nnn given for each 
  file needs 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 number nnn, the full text will be displayed when you press the 
  button "display preferences" in the setting  menu. 
  If the text string is shorter than number nnn, the only effect 
  will be, that the 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.

  Lines may be split in most of the .vst files
  (backslash as last non-blank character in the line to be continued).
  Excepted from this splitting are the files local.vst and install.vst.



  /locals_*/default.vst  default settings; structure:

    Lines in this file may not be continued (splitted)!
 
    all lines:
     cols 1-19               keyword = variable name in xtem;
                             same variable names as in the structure 
                             descriptions for the other files!
     cols 20-end             default for the variable

   remark: if you change a variable, you should pay attention to related
           variables (e.g. if you set variable "editor" to "vi",
           you should also set "edtext", "edxterm" and "edoptions")


  /locals_*/editor.vst  list of editors; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=30     edtext       text (first nnn characters displayed)
     1st param. edxterm      name of the xterm window and parameters for call,
                             if editor needs an xterm window (e.g. vi), 
                             blank otherwise
     2nd param. editor       editor (called in background if followed by &)
     3rd param. edoptions    editor call option string


  /locals_*/index.vst  index preparing program; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=55     intext       text (first nnn characters displayed)
     1st param. index        index preparing program
     2nd param. inoptions    option string for the index preparing program



  /locals_*/install.vst  installation parameters; structure:
 
    Lines in this file may not be continued (splitted)!
 
    all lines:
     cols 1-19               keyword = variable name in xtem
     cols 20-end             default for the variable

     the following variables may be set here:
         versionlerg  text: local appendix to the version string
         fontdli          font used for selection boxes 
         fontbl           font used for buttons/labels 
         fonttt           font used for help texts
                          and for the stdout output of program runs
         fonterr          font used for stderr output of program runs
         fonttsli         font used for TeX syntax helps: selection list 
         fonttstt         font used for TeX syntax helps: syntax
         widthl           width of buttons in the left half of main menu
         widthr           width of buttons in the right half of main menu
         sizeds           size of printer list in printer settings menu
         prtselmaxl       maximum number of lines in criteria lists for printer
                          list reduction (if more entries are found, a scrollbar
                          is generated)
         TeX_syntax_lines number of lines in TeX-syntax widgets
         TeX_syntax_sel   number or lines in TeX-Syntax selection widget
         maxprintcops     maximum number of print-copies

    These variables in /locals_*/install.vst normally will be set by the
    local administrator.
    Yet there may be problems if xtem is installed in a network 
    of computers/X-terminals, if fonts known to a computer/X-terminal are 
    not known to another.
    Thus the user may set his fonts in the following way: set the 
    environment variable XTEMINSTALL to the name of a file which
    contains your "install.vst", i.e. your font settings
    (xtem checks, if an environment variable XTEMINSTALL is set.
     If so, the font setting is read from the file specified in
     XTEMINSTALL instead from the file /locals_*/install.vst).
    The fonts (at least if you use "german" as language setting) should
    include the German-umlaute.


  /locals_*/logform.vst  list of programs/commands for displaying of logfiles;
                         structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=32     logtext      text (first nnn characters displayed)
     1st param. logterm      name of the xterm window incl. options, if logform
                             needs an xterm window (e.g. vi), blank otherwise
     2nd param. logform      Unix-command/editor
                             (called in background if followed by &)
     3rd param. logoptions   option string for this command/editor


  /locals_*/logsuffix.vst  list of suffixes of possible logfiles; structure:
 
    all lines:
     cols 1-... lsuff        suffix of logfile
     cols ...-45             text describing the logfile
                       (lsuff and the following text must be separated by one
                        or more blanks; e.g. ".log   logfile from TeX run")


  /locals_*/mkcommand.vst  list of different forms of mkcommand procedures;
                             structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=65                  text (first nnn characters displayed)
     1st param. mksel        selected form of mkcommand procedures


   /locals_*/preview.vst  list of preview programs; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=50     prtext       text (first nnn characters displayed), this text
                             must be unique to identify this line in the file,
                             commas (",") are not allowed
     1st param. preview      name of the preview program 
                             (called in background if followed by &)
     2nd param. prsuffix     preview suffix: .ps | .dvi
                             (if suffix = .ps then dvips will be started 
                              automatically after a TeX run; this is important 
                              when the preview program is active in background!)
     3rd param. proptions    option string for this preview program
     4th param. ---          preview formats and options associated to this
                             format for the dvips (necessary for postscript
                             previewer such as ghostview) and for the previewer
                             in the following form:
     text1{options_dvips}{options_previewer}[,text2{...}{...}[,...]]

     The format text "text?" is displayed together with "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 "/locals_*/printing.vst".
     "options_previewer" will be added to "proptions".
     "options_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.
     Examples: a) for ghostview (needs dvips!):
        A4_portrait{}{-a4},A4_landscape{-t landscape}{-a4 -swap -landscape}
               b) for xdvi:
        A4_portrait{}{-paper a4},A4_landscape{}{-paper a4r}
     both examples use A4 format in portrait and A4 in landscape.


  /locals_*/printing.vst  printer driver and printer; structure
                         (criteria see printer setting menu
                          and printer list reduction):

    1st line: first non-blank character: field separator for this file
              (any character with exception of "," or "_")
              
              this separator must separate the following parameter:
     1st param. ---          heading for printer names (1st criterion)
     2nd param. ---          heading for printer emulations (2nd crit., part a)
     3rd param. ---          heading for printer drivers (2nd crit., part b)
     4th-10th param. ---     empty
    11th param. ---          heading for printing formats (3rd criterion)
    12th param. ---          heading for 4th criterion
    13th param. ---          heading for 5th criterion
      ...  (the number of criteria is not limited!) 
    the last parameter may be followed by the separator
    example:  
       @ printer @ emulation @ driver @     @              @    @                 @@@@  format     @ double-sided     @ resolution     @ department @ colour @

   all other lines:
     nnn<30     ---          short text for printer,
                             commas (",") are not allowed
     1st param. printer      printer name (1st criterion)
     2nd param. ---          emulation name (2nd crit., part a)
     3rd param. prtdriver    printer driver (2nd crit., part b)
     4th param. prtsuf       suffix for the printfile
     5th param. 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!)
     6th param. lpcmd        print command
     7th param. lpopt        print command option string
     8-10th param. ---       empty (unused)
    11th param. ---          format selection specifications (3rd criterion)
    12th param. ---          value for 4th criterion
    13th param. ---          value for 5th criterion
      ...  (the number of values must be the same as headings given above!)  

    All the parameters starting with the 11th parameter must be of the
    following form:
       text1{options_prtdriver}{options_lpcmd}[,text2{...}{...}[,...]]
    The text "text?" is added to prttext and will be displayed in the 
    "printer selection box" in the "printer selection menu".
    Use the same format texts (11th parameter) as in "/locals_*/preview.vst".
    "options_prtdriver" will be added to "prtoptions".
    "options_lpcmd" will be added to "lpopt".
     The number of triples "text{...}{...}" (at least one) is not limited.
     Example:
       HPLaserjet IV    @ xlw3 @ Postscript @ dvips @ .ps @                 @ lp @ -c -dxlw3 @@@@ A4_portrait{}{},A4_landscape{-t landscape}{} @ single-sided{}{-dsimplex},double-sided{}{}@300dpi{}{},600dpi{-P xlw3}{}@LRW@sw@


  /locals_*/prt_dvijep.vst  page selection: same structure as prt_dvips.vst
  /locals_*/prt_dvi???.vst  page selection: same structure as prt_dvips.vst

  /locals_*/prt_dvips.vst   page selection; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=85     prmtext      text (first nnn characters are displayed)
     1st param. prmrelabs    r : the user may select the start and end page to
                                 be printed as relative page numbers
                             a : the user may select the start and end page to
                                 be printed as absolute page numbers
                             (blank) : all pages must be printed, i.e. page
                                       selection is forbidden (e.g. a5booklet)
     2nd param. prmsel       by this parameter the corresponding commands in
                             procedure prt_dvips will be selected 
                             (file prt_dvips.tcl, see below)


  /locals_*/spellcheck.vst  list of spelling check programs; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=80     sptext       text (first nnn characters displayed)
     1. param   spcmd        name of the spelling check program
     2nd param. splang       language: may be used to select the dictionary
                             when calling the spelling check program
     3rd param. spcorr       = "K" if the spelling check program possibly 
                                   changes the text file
                             = " " otherwise
                   if the spell check program may possibly change the text 
                   files, 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 spelling check program.
     4th param. spselect     empty (unused!)
     5th param. spoptions    option string for the spell check program


  /locals_*/suffix.vst  list of suffixes in the edit settings menu

    all lines:
     1-end      esuff         suffix  ( * | .tex | .aux | ... )


  /locals_*/syntax.vst  list of syntax check programs; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=55     sytext       text (first nnn characters displayed)
     1st param. syntax       name (call) of the syntax check program
     2nd param. syoptions    option string for the syntax check program

 
  /locals_*/texfmt.vst  list of TeX formats; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=20                  text (first nnn characters displayed)
     1st param.  texfmt      TeX format (tex | latex | slitex | ...)


  /locals_*/texsize.vst  list of prefixes: size of TeX programs;
                               structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=20     texmtext     text (first nnn characters displayed)
     1st param. texmem       prefix for tex program 
                             (normally left blank or "big" otherwise)


  /locals_*/texsuffix.vst  list of suffixes for TeX files (TeX settings menu)
                           also used for "additional programs"
                               structure:
    all lines:
     1-end      texsuffix    suffix  (.tex | .ltx | .doc | ... )


  /locals_*/utility.vst  list of additional programs; structure:
 
    1st line: first non-blank character: field separator for this file
    all other lines:
     nnn=50     uttext       text (first nnn characters displayed)
     1st param. utcmd        command name
     2nd param. utoptions    option string for this command



  The variable name is added in the preceding list, if it is used in the 
  setting files "/locals-*/default.vst", $HOME/.xtem.vst and in the .vst-file 
  associated to the actual .tex-file.

  More variables, which are set in the setting file "default.vst":

     edsyntaxhelp  yes | no
                     yes: when the editor is called, additionally a window with
                          the names of the LaTeX commands will be created. 
                          By clicking one of the commands, a window with the
                          syntax and a short description plus example to the 
                          command will be created  (only for those formats 
                          "xxx", for which a directory
                                   .../xtem/help_*/xxx_syntax/
                           is present)
     prtfilperm    non-permanent | permanent (language dependent, see below)
                     non-permanent: the file to be printed ($prt_file) will be 
                                    deleted after printing
                     permanent: the file to be printed ($prt_file) will not be
                                    deleted after printing
                   these values must be identical with the strings given to the
                   variables vv(dm19)/vv(dm20) in the file 
                   "/xtem/help_*/button.texts".
     texmax        maximum number of TeX runs  ( 1 | 2 | 3 | 4 )
     prpreopt      option string for the dvips run, if such a run is necessary
                   before a preview start (necessary before ghostview e.g.)
     prformat      actual selected format for the preview program
     prtformat     actual selected format for printing
                   usually "prformat" "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!)
     prtselstr     string, containing all selection criteria to identify
                   a printer setting
     prtpresel     string, containing asterisks "*" or the specified
                   criteria for printer list reduction.

  All variables set in the file "/locals_*/default.vst" are read when you
  click on "reset to defaults", the user may save his actual setting by 
  clicking on "save preferences" in the main menu: they are written identically
  into 2 files:
  a) in the actual directory in a .vst-file associated to the actual .tex-file,
  b) in the "$HOME" directory in file ".xtem_*.vst" (* stands for the language)
  They have the same structure as the file "/locals_*/default.vst":
     cols 1-19               keyword = variable name in xtem;
                             same variable names as in the structure 
                             descriptions for the other files!
     cols 20-end             default value for the variable



VI. Programs needed with the given Setting Files:
-------------------------------------------------

  The local administrator should install all .vst-files carefully and test them:
  if a not-existent program is called, Tcl/Tk breaks down with an "X-error"!
  In this case you get a glance of what should be called by selecting
  mkcommand.0 as exec mode.
  In this version of xtem we use the following programs/scripts:

    editor:              emacs       vi
    dvi-driver:          dvidvi      dvijep      dvips
    TeX:                 tex         latex       latex209
    previewer:           ghostview   xdvi
    spelling check:      spell       ispell
    syntax check:        texchk
    index preparing:     makeindex
    bibliography:        bibtex
    protocol files:      cat         pg          (plus editor list, see above)
    additional programs: umcod
    syntax help:         gunzip      xdvi

  Thus we recommend to execute the following Unix commands and look at the
  results:

    which                emacs       vi
    which                dvidvi      dvijep      dvips
    which                tex         latex       latex209
    which                ghostview   xdvi
    which                spell       ispell
    which                texchk
    which                makeindex
    which                bibtex
    which                cat         pg 
    which                umcod
    which                gunzip      xdvi



VII. Help Information 
---------------------

  To each widget a file with a help text is associated.
  In this version the filename is displayed at the top of the help text;
  this makes it easy to the local administrator to modify the help texts.
  (if you want, remove the following lines:
     $f insert end "----- $vv(aus5): $dnam -----\n";### this line may be removed
   in the file "ut.tcl" (procedures "cat_file0" and "cat_file"))

  The right mouse button is used only for getting help.
  Consequently by clicking the right mouse button, the user will get help
  to this special button etc., where he actually clicked.
  
  /help_*/...           If you modifiy the .vst-files, you probably also have to
                        modify the helpfiles.

  /help_*/xt_localnews.hlp      By this file the local administrator is
                                given a pinboard for TeX news,
                         this file is displayed, when you click on 
                         "local news" in the main menu.



VIII. LaTeX Syntax Help:
------------------------

  There are syntax helps for nearly all LaTeX commands in hypertext, 

    /help_*/miscellaneous/*.htx
    /help_*/latex/*.htx  

  In these files you will find the syntax  which is used for the 
  online-help whilst editing.
  This is an open list of files, i.e. by adding new files new help is added 
  to the latex syntax help menu.
  You may also add new directories for other formats 
  (e.g. /help_english/tex/*.htx).
  For details see README.htx
  
  For most of these files exist examples and dvi-files+bitmaps with 
  the LaTeX output for these examples.
  The bitmaps were generated from the dvi files by means of xv 
  (grabbing from an xdvi or ghostview representation of the dvi file)
  These bitmaps were saved in the files 
    .../xtem/help_*/latex/*.xbm
  and then packed with     gzip -9 ...  (pack option: -9)  into
    .../xtem/help_*/latex/*.xbm.gz
  When a bitmap is to be displayed, a copy will be unpacked, 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 by unpacking when syntax helps are used.

  You may also delete all files 
     .../xtem/help_*/latex/*.xbm
     .../xtem/help_*/latex/*.xbm.gz
  in this case the files 
     .../xtem/help_*/latex/*.dvi
  are displayed by means of the program    xdvi

  If neither   gunzip   nor   xdvi   is available at your installation,
  you have to modify the procedure
       hlpwin_bitmap
  in file ts.tcl. In this case, please inform us so that we can extend
  ts.tcl for future releases.



IX. Adding a new Printer Driver:
--------------------------------

  For each printer driver (its name beeing represented by "???") 
  you have to create two files:

       prt_???.tcl               according to     prt_dvips.tcl
       /locals_*/prt_???.vst     according to     /locals_*/prt_dvips.vst

  (i.e. here the printer driver  dvips  may serve as a model).

  and you have to add a line to file "tclIndex":

       set auto_index(prt_???) "source $dir/prt_???.tcl"


X. Other Files which may be changed by the Local Administrator
-----------------------------------------------------------------

  In order to make the installation of future releases easier to you,
  only the following files may be adjusted by the local TeX administrator
  to the local installation:

     bibliogr.tcl
     printing.tcl
     editor.tcl
     index.tcl
     logfile.tcl
     newsfile.tcl
     preview.tcl
     spellcheck.tcl
     syntax.tcl
     tex.tcl
     xtem_prog
    
  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.


  Most of the Tcl commands used in these files are self-explaining.
  Unusual to the newcomer in Tcl may be:
    glob -nocomplain -- *       unsorted filelist of the actual directory
    lsort ...                   sorting of a list
    unlink -nocomplain ...      delete of a file
    frename ... ...             renaming a file (same as "mv" in Unix)


  If new procedures are added, their names must be added to the file tclIndex 
  too. This may be done manually or by means of the Tcl commands:
                          $ wish
                          wish>auto_mkindex . *.tcl
                          wish>Ctrl-d


  ============================================================================= 
     All other files except these ones described in sections V. - X.     
     may only be changed in contact with the authors.
  ============================================================================= 


XI. Executing Programs (Program Calls): mkcommand
-------------------------------------------------

  Each file mentioned in the preceding section 
  includes at least one program call, in general with 2 parameters:
    1. parameter: text widget, into which the output of the program call
                  and further messages are written.
    2. parameter: string variable "austext", into which in this procedure text 
                  may be written by means of variable "a".
  More text may be written into the text widget by means of the procedures
  "writescr" and "writescr0" (see below).
  All other variables may be accessed by means of global commands.

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

  1)  mkCmd_wait  $f  command [list "list_of_parameters/options"]
      eval  mkCmd_wait  $f  command [list "list_of_parameters/options"]

         call of dvips as an example:     
  1a)           mkCmd_wait  $f  dvips [list "$prtoptions $main_file"]

         call of ls as an example:
  1b)           mkCmd_wait  $f  ls [list ""]
        
      mkCmd_wait assumes the 2nd argument as the command to be called,
      the string following to the keyword list (enclosed in "...")
      is taken as the parameter list for this command. If the command
      is to be called without parameters, there must be an empty list
      as in example 1b).
      Output of the command is put into the widget  $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
      mkCmd_wait) is available in a variable, thus killing of a running process
      is possible: button "cancel" in the xtem main menu.
      Processes generated by mkCmd_wait may also be terminated as usual:
                Ctrl-d          EOF
                Ctrl-c          interrupt
      Error output of the command (stderr) is put into the same widget, 
      by choice in another font type ( file "/locals_*/install.vst", 
      variable "fonterr", see preceding variable description).

      
  2)  eval catch "exec dvips $main_file.dvi" message
  3)  eval set res [catch "exec dvips $main_file.dvi" message]

      calls a program (dvips) and gets its output (which may then be passed
      to the text message widget).
      By this you may likewise call programs, which generate their own
      window (such as xdvi, ghostview, emacs).


  4)  eval set res [catch "exec xterm -e $editor $edoptions $ed_file $edback" \
                                                                       message]
      calls a program (stored in $editor), which must run in an xterm widget;
      e.g. the vi editor only run in an xterm widget!

  Calling with eval is recommended and is necessary, if an option string
  may be empty. Otherwise in case of empty option string there would be an
  additional empty parameter, which causes problems e.g. for emacs, vi,
  some printer drivers!
  Program calls using catch give different results in res and message
  (names of these two variables according to the preceding examples):
  - call in foreground:
                res           return code
                message       standard output (stdout) and error output (stderr)
  - call in background:
                message       PID (since Tcl version 7.0, empty string formerly)
  For more details see the Tcl manual/man pages.


  Output may be put into the text message widget by means of the procedures:
       writescr0  $f "text"
       writescr   $f "text"
  $f is the variable name which contains the text message widget name.
  It is given as the first parameter of the procedure call.
  Normally the text should be put within double-quotes.
  If using "writescr0", the text will be put into the widget starting at
  line 0, (i.e. the former contents will be deleted), otherwise the text
  will be appended.



XII. Variables used for Process Administration:
-----------------------------------------------

   Process administration is done by means of the following variables:

        sub       = 0     no foreground processes are active
                          (most buttons unlocked except "cancel" and buttons
                           with active background process(es))
                  = 1     one or more foreground processes are active
                          (all buttons locked except "cancel" and "unlock")

        p_mkCmd   = PID   process Id of the process which was last started
                          by mkCmd_wait (Tcl version >= 7.0) until termination
                  = 1     otherwise

        edsubback  = 0    no editor (started in background by xtem) is active
                          (i.e. = 0 until call of an editor in background by 
                          xtem; will be reset to 0, when xtem notices, that
                          all editors started by xtem are no longer active;
                          this check is possible in Tcl version >= 7.0)
                   = PID  editor was started in background and PID is
                          known (Tcl version >= 7.0); if more than one editor 
                          was started this is the PID of the last started
                          editor call.

       prsubback          same as edsubback, for preview program
       logsubback         same as edsubback, for "protocol file"




XIII. Installation of the Manual Page:
--------------------------------------

   Install the manual page xtem.1




XIV. Files in the User's Directories, which are read/written by xtem:
---------------------------------------------------------------------

   .lastxtem             - is  written when "save preferences" is clicked,
                         - is read at start of xtem,
                         - contains the filenames at the moment of last "save".

   ???.vst               - is written when "save preferences" is done.

   $HOME/.xtem.vst       - is written when "save preferences" is done.

  At start of xtem or when "load preferences" is clicked, the file "???.vst"
  is read --- where ??? stands for the mainfile (.tex-file which will be used 
  when TeX is called). 
  If it doesn't exist, the file "$HOME/.xtem.vst" is read instead.
  If this file doesn't exist likewise, the file 
  "$XTEMPATH/xtem/locals_*/default.vst" is read.
 


XV. Program "umcod":
--------------------

  The added program "umcod" is written in C and compiled with Gnu gcc compiler
  with system Sun/SOLARIS and makes different code changes:
        
        German umlaute   <--->  corresponding TeX- or german-TeX commands
        8-bit-IBM        <--->  8-bit-ISO
        Unix file        <--->  DOS-file    (CR/LF!)
        tabulators        ---> expanded to blanks  (tabulator-stops at 
                                                    pos. 8,16,24,..)

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


----------------------------------------------------------------------------

If nothing else helps, contact:

  questions concerning xtem:
        weibezahn@lrw.uni-bremen.de    phone. +421 - 218 - 3532
    
  special questions concerning the installation of Tk, Tcl, TclX:
             lotz@lrw.uni-bremen.de


----------------------------------------------------------------------------

Known problems:
===============

- message
     'can't read "tk_priv(relief)": no such element in array ...'
  (occasionally in certain constellations at left mouse clicks)
  seems to occur only with Tcl version < 7.0!

- message
     'selection doesn't exist or form "STRING" not defined'
  (when 3 or more mouse clicks immediately instead of double click in 
   select boxes).
  action to be done: click on "OK"-button

- message
     '... file10 does not exist ...'
  (occasionally after program execution)
  seems to be a synchronization problem after program termination in TclX,
  seems to be system-dependent (e.g. Linux) and load-dependent
  action to be done: click on "OK"-button

- Call of a non-existing program results in annoying and confusing situations.
  This can only happen, if the local administrator has not installed all
  programs listed in the files   /locals_*/*.vst
  a) if a "program not found" was called by means of "mkCmd_wait",
     this results in an X11 error message:
     '... X Error of failed request ...',
  b) if a "program not found" was called in background by means of 
     'catch "exec ..."',
     the resulting error message may be written to the xterm window.
  If you click on "exec mode" in the main menu of xtem and then select
  mkcommand.0, you may see what should be called via "mkCmd_wait"!
     
----------------------------------------------------------------------------

During installation of xtem on different systems we heard of the 
following problems:

AIX version ??? : right mouse button doesn't give help texts, instead of this:
                     "Restore", "Move", ... "Close" -Widget
                  error cause: in the file "system.mwmrc"
                               (in /usr/lib/X11/ or /usr/lpp/X11/lib/X11/ )
                               exists a binding
                                   Buttons <Btn3Down> ... window

AIX version ??? : use "aixterm" instead of "xterm" in the files
                  "/locals_*/*.vst", especially for calling TEN/PLUS editor.

Sun SOLARIS2.x  : be sure, that BSD commands cannot be found during installation
                  of Tcl/Tk/TclX (PATH must not include "/usr/ucb")!

----------------------------------------------------------------------------

************************************************************************
************************************************************************
**                                                                    **
** In any case after successful installation, please send an e-mail   **
** to                                                                 **
**                                                                    **
**                     weibezahn@lrw.uni-bremen.de                    **
**                                                                    **
** with answers to some or all of the following questions:            **
**                                                                    **
************************************************************************
************************************************************************

 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:
 TclX-version:
 addinput-version (if installed):
 
 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:

 
**********************************************************************
**********************************************************************
