Additional help for XTeXShell Version 0.91
------------------------------------------

A manual for XTeXShell is in preparation and will be out soon.  If you have
worked with BORLAND or TURBO C, C++, or Pascal before, you won't have
problems to use XTeXShell. If not, please read the help pages about XTeX from
the main XTeX-window and try what the menu entries and buttons do.


Start XTeXShell with

        xtexsh [filename] [-m mainfilename]

If you specify filename, XTeXShell will automatically start the editor and
load filename. 

The XTeXShell editor hates tabs and replaces them with spaces when loading
a file. This can take a while if you have large files, because a Tcl program
isn't as fast as a compiled program.  In that case, you may wish to convert
your text file before loading it into the editor, for example with the
program TFC.


The following sections are information about features and the way XTeXShell
works, which you probably won't find out by trying.

1) HyperText-Help

From the XTeXShell-Editor, you can get online-help for LaTeX-commands by
   - moving the mouse pointer on the word you want help for and press
     the right mouse button
   - moving the cursor on the word you want help for and press Ctrl-F1
   - Select LaTeX Help Index in the Help menu


2) X-Selection

You can insert the X-Selection in the XTeX-Editor with a double click on
mouse button 2.  This change to the normal X-definition (single click) was
necessary, because Tcl/Tk allows fast scrolling by moving the mouse with
button 2 pressed and I wanted to keep this feature.  See "XTeX-Editor help"
entry in help menu for a detailed explanation of key/mouse functions.

------------------------------------------------------------------------------
*** If you are a novice user, you don't need to read the rest of the document!
------------------------------------------------------------------------------

3) Setup System

During Initialization, XTeXShell reads information and it's default values
from a setup file and a shortcuts file.  Because XTeX was designed for a
multiuser system, the setup system is more complicated than in a single-user
environment:

   - Setup system.  The default variables for XTeXShell are stored in the
     setup files. Initialization is done in 3 steps:

      1) XTeXShell loads the system-wide setup information.  This is either
         the  file "setup.orig" in the XTeXShell root directory, or if exists,
         the file "setup" in the same directory.  Both files must be valid
         Tcl/Tk scripts.

         "setup.orig" is the original setup file and you should *NEVER* change
         it. If you want to modify default values, copy this file to "setup"
         and make your system specific modifications there!

      2) After completing system setup, XTeXShell continues with the user
         setup. If available, it will read the file ~/.xtexsh.setup. Defaults
         for users should go here.  For creating your own ~/.xtexsh.setup file,
         copy the file "setup" from the XTeX root directory.
         An easier way is to use Options/Save options/Save global
         function from the XTeX-Shell which will make the copy automatically
         if no user setup file is present.

      3) Sometimes it is nice to have special default values for a particular
         task.  Therefore the last step of XTeXShell is to try to read the
         file "./.xtexsh.setup" in your current directory. This means that you
         can make the behavior of XTeXShell dependent on the directory where
         you start it.
         If you want to use this feature, copy the file "~/.xtexsh.setup" to
         your current directory.  You can also use the function Options/Save
         Options/Save Options Local, which will automatically make a copy, if
         the file doesn't exist.

   - Shortcuts.  The entries of the Shortcuts-menu and the text which is
     inserted after invoking a shortcut is stored in the shortcuts-files.
     Initialization happens in the same way as the setup-files, but the
     filenames are:

         (XTeXShell-Root)/shortcuts.orig
         (XTeXShell-Root)/shortcuts
         ~/.xtexsh.shortcuts
         ./.xtexsh.shortcuts

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

3) File formats:

   - Shortcuts: The file format for the shortcuts files is quite simple.

      :entry entry-name
        text
      :endentry

     entry-name will occur in the shortcuts menu and text will be inserted
     to your file after pressing entry-name.  A line with

      :separator

     may be inserted after :endentry which inserts a separation line in the
     shortcuts menu.

   - /help/help: help pages for online hypertext help are stored in this file

        :entry
          entry-name1
          [entry-name2]
          ...
        :header
          text
        :name
          text
        :synopsis
          text
        :description
          text
        :example
          text
        :endentry

        :entry and :endentry are mandatory, everything else is optional.

     text may contain the following formatting commands:

        :ul
        :li text
       [:li text]
        ...
        :eul

        :el
        :li text
       [:li text]
        ...
        :eel

        :dl
        :li definition text
       [:li definition text]
        ...
        :edl

     These environments produce environments similar to the itemize and
     description environments in LaTeX.

        :tt        - select typewriter font
        :em   word - next word italic
        :bold word - next word bold
        :hl   word - next word is a hypertext link. If the user clicks the
                     mouse on this word, the page with the name word will be
                     loaded.  If word ends with a "_", XTeX will read and
                     display the bitmap file "word" in the subdirectory
                     bitmaps.

     After modifying the help file, you will need to run the shell script
     update_help in the help directory

     This shell script will create the file help.index which is the index
     file for the help system.  Each line consists of an entry name and the
     filename and position (in bytes) where the help text for the entry
     starts.


4) Known Bugs

   - The Purge Button doesn't work -- yet

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