========================================================================
                    Compiling the EPM TeX Front End
========================================================================

Contents
--------
   Overwiew
   Compiling a TeX Front End module for the EPM
   Compiling an EPM with integrated TeX Front End
   "Classic" vs. "VTeX" version
   Configuration constants and extra features
   Sample EPM configuration files
   Debugging



Overview
--------
The E language source code of the EPM TeX Front End is provided, so that
you can generate either

* a module texfe.ex, whihc can be added to an existing EPM

* a complete EPM with integrated TeX Front End

Furthermore, you can choose between two `flavors' of the TeX Front End:

* `VTeX':  A version of the TFE to be used only with VTeX/2

* `classic':  This version works both with traditional TeX systems (such
  as emTeX) and with VTeX/2; however, certain convenient VTeX-spacific
  features cannot be provided.  Instructions for installing and usage of 
  this variant are provided in the file classic.txt.
  
The ready-made module shipped with the distribution constitutes the
version for use with VTeX only.



Compiling a TeX Front End module for the EPM
--------------------------------------------
Compiling the file texfe.e by

        ETPM texfe

generates the module texfe.ex. (Please, read the following sections 
before actually compiling!)



Compiling the EPM with integrated TeX Front End
-----------------------------------------------
Creating an EPM with integrated TeX Front End requires the following
steps:

1) Add the contents of MYSTUFF.ADD to your file MYSTUFF.E 
   (In case there is no the file MYSTUFF.E does not exist, simply
   rename MYSTUFF.ADD to MYSTUFF.E.)

3) Provide a suitable configuration file MYCNF.E.  (See the sample
   MYCNF.SMP that comes with the distribution.)

4) Compile the EPM, including the settings defined in MYCNF.E:

        ETPM epm

Caution:  Do not attempt to link texfe.ex or tex.ex once again!



"Classic" vs. "VTeX" version
----------------------------
This is controlled by the compile-time variable vtex, which may or may
not be defined in the general EPM configuration file MYCNF.E.

The statement

        define vtex = 1 
  
causes the EPM TeX Front End for VTeX/2 to be generated.  Without this
variable, the `classical' TeX Front End for use with emTeX or Web2c will
be compiled. 



Configuration constants
-----------------------
The following const's are read from the file MYCNF.E:

NLS_LANGUAGE

    Set this const to 'DEUTSCH' in order to generate a German version.
    Languages other than English (default) and German are currently not
    supported.  Caution:  In order to compile a German version of the
    full EPM you need the file DEUTSCH.E which is NOT part of the free
    EPM package!

WANT_TEX_MENU

    Define const WANT_TEX_MENU = 0 in MYCNF.E to omit the TeX menu.  The
    default value is 1, so that the menu is usually included.  Creating
    the (V)TeX Front End without a menu is not recommended, unless you
    supply a suitable toolbar!
    
WANT_TEX_HOTKEYS

    Define const WANT_TEX_HOTKEYS = 0 in MYCNF.E to supress the
    definitions of the hot-keys Ctrl-F9...F12 and Ctrl-v, in case they
    clash with other modules.

LATEX_SYNTAX_INDENT

    Indentation within LaTeX environments.  The default value is 2 (not 
    depending on SYNTAX_INDENT).
    
WANT_STREAM_INDENTED

    This const applies to the the basic EPM, not to the TeX Front End.
    Setting it to 1 makes the <enter> key move the cursor always to the
    starting column of the previous line.  This is useful in conjunction
    with EPM's syntax assist for LaTeX and other `languages'.  Defining
    WANT_STREAM_INDENTED requires, however, compilation of the full EPM,
    either with or without built-in texfe.
    
WANT_CTRLA

    const WANT_CTRLA = 1 will map the bracket matching facility of the
    EPM, which is usually triggered by Ctrl-[, to the Ctrl-a key, too.
    This is particularly useful with, e.g., the German keyboard, where
    the original key assignment would require pressing Ctrl-AltGr-[.
    The German versions were compiled with this feature turned on.

WANT_INCLUDEONLY_SUPPORT

    const WANT_INCLUDEONLY_SUPPORT = 1 will enable a special facility
    related with master file support:  When master file support is ON
    and TeXing is requested while an included file is being edited, then
    the EPM will search the master file for an \includeonly command and
    will replace its argument with the name of the file being edited.
    If there is no \includeonly command found, or if it has been
    commented out, _all_ dependent files will be included, as usual.  
    The facility is disabled, when a marked region is to be typeset.
    
    Notice some important restrictions:
    
    * Only the stem of the filename (neither the path nor the extension)
    is passed to the \includeonly command.  As a result, the included
    file must reside in the same directory as the master file, it must
    be of type '.tex', and the path must not be specified.
    
    * The filename is passed in lowercase to the \includeonly command,
    so you have to use lowercase in the corresponding \include command,
    too.
    
    * The \includeonly command must not be split into two or more lines.
    
    * The \includeonly command must be the only command in the line.
    


Sample EPM configuration file
-----------------------------
The free EPM differs very much from the version shipped with Warp 4,
most noticeably as far as the menu structure is concerned. 
Unfortunately the help texts and the User's Guide reflect the Warp 
version, and there is no configuration file included with the "BBS"
package to create the latter.  Besides, there are some features missing
in the BBS version.

I have provided a configuration file MYCNF.SMP, which includes all the
information required to create the "Warp 4 EPM".  Rename it to MYCNF.E
to make the compiler include it.  The file contains information how and
where personal settings and useful extras like syntax assist can be
added.  I recommend including this file, when compiling an EPM with
integrated TFE.  Re-compile the spell-checking module EPMLEX, too, using
this MYCNF.E!

Please, note the changes to MYCNF.SMP introduced with v2.2:  Syntax
assist for C and Java is now enabled, and a bug with the TAGS facility
has been fixed.  As with v2.4, the EPM will be configured so as to 
auto-convert Unix-style line endings to DOS style.



Debugging
---------
The TeX Front End provides the EPM command

        tex_debuglevel

Enter this command to see the current debug level, initially 0. Enter

        tex_debuglevel 1|2|3

to get debugging information in the EPM message line:

  Debug level  | Action 
  --------------------------------------------------------------
  > 0          | trace all 'cd' commands
  = 1          | display the external commands to be launched
  > 1          | trace parsing of the TeX transcript file
  > 2          | ditto, but lots of information (don't use it!)
  

The debug level is set to 0, when the EPM starts up.

-- finis

