                         TeX-Shell
                         =========

          a multitasking TeX-Shell for
             Lindner TeX & N.AES

          (c) Axel Kaiser
              axel.kaiser@rz.ruhr-uni-bochum.de

This is a preliminary draft of a description of my TeX-Shell.

Standard disclaimer:
--------------------

 TeX-Shell COMES WITH ABSOLUTELY NO WARRANTY, NOR WILL I BE LIABLE FOR ANY
 DAMAGES INCURRED FROM THE USE OF IT. USE ENTIRELY AT YOUR OWN RISK!!!

The TeX-Shell, as many TeX utilities, is free software. This means
that you can give it away to anybody but only without charging.
In order to put it on a PD disk or a CD you need my written
agreement. You may make it downloadable in a mailbox but only
if there is a possibility of free guest download.

Requirements:
The TeX-Shell needs (besides an Atari TOS computer) a TeX system
(otherwise you wouldn't want to use it) and the N.AES MultiTOS
replacement of OverScan Berlin, Germany. If there is the need
for general multitasking support (i.e. Magic, MultiTOS, ...)
ask me for this, perhaps I will make TeX-Shell run under these
systems too. It offers special support for the Lindner TeX
implementation, as it supports its 'edit file in case of an error'
mechanism.

There is now a new version of TeX-Shell available, which
opens a window. Using this window should be easy, try holding
the control or the alternate key while clicking on file names.
There is currently no english documentation for this version
(but a German version in LaTeX format :-)  ).
I am looking for people who would like to help me translating
the documentation (maybe I translate the German documentation
to English words which you translate into an English document).

By the way: as of version 1.00 TeX-Shell is postcardware, so
please send me a nice postcard if you are using it.

By the way 2: if somebody wants to translate TeX-Shell and
documentation into a third language please call me!


The TeX-Shell is configured by builtin parameters
(which can be set with the Setter program) and/or
the file TEXSHELL.INF which is described below
(the example shows the standard values for the parameters)

------------- cut here --------------
% Like in TeX comments begin with a %
%
% The parameter starts with the first non-space
% character following the = and contains
% all the following characters in the line,
% i.e. there can be no comments be attached to
% the parameters.
TEX_PROG    = E:\TEX\TEX.TTP
TEX_CMDL    = -j -s E:\TEX\TEXSETUP
TEX_DEFAULT = latex2e
TEX_FORMATS = latex2e,plain,myformat
DVI_PROG    = E:\TEX\DVI.APP
DVI_CMDL    =
DVI_FILES   = E:\TEX\TEXOUT\DVI\
EDIT_PROG   = E:\EVEREST\EVEREST.PRG
EDIT_CMDL   =
FILE_TEX    = D:\TEX\
FILE_EDIT   = D:\TEX\
------------- cut here --------------

- TEX_PROG contains the name of the TeX program
  (I suggest to use Lindner TeX, as the TeX-Shell
  uses the parameter -e of the Lindner TeX.)
- TEX_CMDL contains additional options for TeX.
  The parameters given hear mean that TeX doesn't
  wait for a keystroke in the case of an error
  (-j) and that it should read its defaults
  from the file E:\TEX\TEXSETUP (-s).
- TEX_DEFAULT contains TeX's default format (without
  the ampersand und the file ending).
- TEX_FORMATS contains up to 7 formats, which then
  can be choosen in the format dialog's popub box.
- DVI_PROG contains the complete name of the DVI preview.
  I prefer the DVI program by Markus Pristovsek, which can
  also be used to print the document (because of this there
  is no special support for a printer driver program).
- DVI_CMDL contains additional parameters to the
  dvi driver.
- DVI_FILES contains the folder for the .DVI files.
  Please note the following backslash '\'.
- EDIT_PROG contains the path to the preview. I prefer
  the DVI program by Markus Pristovsek, which can also be used
  to print the document (because of this there is no special
  support for a printer driver program).
- EDIT_CMDL contains additional parameters for the editor.
  This option is not yet used.
- FILE_TEX contains the name of the TeX file.
- FILE_EDIT contains another name which will be used
  in adjunction to the TeX file when calling the editor. This
  is usefull when the TeX source is split over two or more files.

If there is no .INF file TeX-Shell uses its build-in defaults,
which can be changed with the program SETTER which can be found
in the HSMODEM package, for example. I suggest you use the GEM
version of SETTER as the TOS version doesn't support spaces in
strings, as are needed for the TeX commandline.

The TeX-Shell is aware of two environment varibales:

AVSERVER (defaults to THING) is the name of the desktop you use
under N.AES. This isn't needed unless you want the TeX-Shell to
be able to start the editor and preview.

TOSWIN (defaults to GEMTERM) contains the name of the terminal
program you use to run TOS programs in yout multitasking environment.
This name is only used for task switching: when the TeX-Shell runs
the TeX program it tries to top the window in which TeX's output
is written.

When you use an editor which understands the ES protocol
(and is able to send the AV_SENDKEY message) you can use most
of the TeX-Shell from inside the editor. TeX-Shell understands
the ES_MAKE message which causes TeX-Shell to start TeX on the
current TeX file. The details depend on the editor you use.

The menus of the TeX-Shell should be self-explanatory.

Features:
---------
The TeX-Shell understands one paramter, which can be specified
when starting it. This may bei either a .INF file or a .TEX
file with the obvious meanings. This makes it possible to use
TeX-Shell as an application for .INF and .TEX files.

Another feature is that TeX-Shell is in some cases able to guess
the format needed to TeX a file. First there is a secure
method: write a line containing
macropackage = <format>
or
format <format>
at the beginning of your TeX file (the TeX-Shell searches
the first 10 lines). You should place a '%' before the
format specification so that TeX will not complain.

If your TeX file contains the string "\documentclass" the
format latex2e is choosen, in the case of "\documentstyle"
a lplain seems the proper choice and when there is a
"\magnification" it should be a plain TeX file.

In any case the first lines which matches any of the above
criterions decides the choosen format.

Problems:
---------
The TeX-Shell isn't very error resistent.

Documentation:
--------------
The english documentation is very sparse and is supposed to contain
many errors and to be written in bad english. You are encouraged
to change both these problems. I didn't want to spend too much time
writing a documentation which nobody wants to read. This means,
there more you write me comments, suggestions and bug reports the
longer the documentation will become. Please support free software.

P.S. The development of the TeX-Shell heavily depends on the
user feedback. So I am looking forward to your suggestions and
comments.
