========================================================================
              The EPM TeX Front End ("classical" version)
                 an integrated TeX environment for OS/2
========================================================================
                                                             Version 5.4
                                                              2004-07-25


The EPM TeX Front End is an additional module for the OS/2 "Enhanced
Editor" (EPM).  It turns the EPM into an integrated TeX environment,
providing (La)TeXing, dvips, previewing, etc. from within the editor.
It can be used with various TeX systems, including emTeX and VTeX/2.
Special features are:

  - Optional TeXing of a marked region of a file
  - TeX errors are marked and explained in the source code window.
  - Postscript support (dvips conversion on-the-fly)
  - Support for documents spread over multiple files
  - Optional LaTeX syntax assist
  - OS/2 shell and WPS interface

The TeX Front End is shipped as a precompiled .ex module which can be
added to an existing EPM.  From version 5.4 on, the precompiled module
provides also those features that were formerly available only when the
TeX Front End was compiled into a customized version of the EPM.



CONTENTS:

Part I: Installing the TeX Front End

1. Installing/Updating
2. Checking the initial configuration

Part II: Using the TeX Front End

1. The TeX menu
2. The hot-keys                                
3. LaTeX and other formats
4. Master file support
5. TeXing a marked region of a file                 
6. LaTeX syntax assist
7. Syntax Highlighting

Part III Advanced configuration
1. File types
2. External programs
3. The configuration tool TFCONFIG
4. The Icon

Appendix

   Known bugs
   Distribution and support
   Credits
   

========================================================================
                    I. Installing the TeX Front End
========================================================================



The file NEWS lists all changes applied from one version to the next.



1. Installing/Updating
----------------------
Before installing the TeX Front End, please check make sure that

   * you have installed the "Enhanced Editor" EPM v6.03b, which is
     shipped with Warp4 (_not_ Warp3) or can be obtained for free from
     various sources;
   * you have already installed a working TeX system.

Installing the EPM TeX Front End requires three steps to be performed:

   (1) Compiling a module texfe.ex or a full EPM with integrated
       TeX Front End.
   (2) Copying the required files to the EPM directory
   (2) Making the EPM import the .ex module -- unless you have created
       an EPM with integrated TeX Front End

   As to step (1), please refer to the file compile.txt.
   
   (2) The following files must be copied to the directory where
   the EPM resides on your system (the "EPM directory").  Usually this
   should be the directory OS2\APPS of the boot drive:
   
     tfconfig.cmd
     tfefm.cmd   
     texfe.ex (not required, if you have created an editor with 
              integrated TeX Front End)

   (3) If you have created the module texfe.ex, the EPM must be
   configured to link it at startup.  Include the line
   
     'link texfe.ex'
   
   to the REXX profile, i.e, the file profile.erx in the EPM directory.
   The quotes are part of the information!  Enable the EPM option "REXX
   profile" in the EPM "Settings" notebook.  (NB:  A sample REXX profile
   profile.smp containing various useful startup actions is part of the
   distribution.)

After closing and restarting the EPM, the "TeX" menu should appear;
clicking on the menu item TEX/ABOUT should show the version number 5.4.



2. Checking the initial configuration
-------------------------------------
After installing the TFE for the first time or after updating from a 
previous version, several settings should be checked:
   
Click on the menu item TEX/SETTINGS.  The settings of the TeX Front End
can now be changed by double-clicking on the particular item or by
selecting it and clicking on MODIFY then.

The items #1...#5 and #12 need not be changed now; they will be
explained in Part II of this document.

#6, #7 and #8 are the EPM commands to start the previewing programs for
DVI, PostScript and PDF files.  The EPM starts external programs using
the "start" command, which you know from the OS/2 command prompt.  A
binary (.exe) program is launched by "start /n", whereas a batch file
(.cmd) must is executed via "start /c".  All programs will be executed
in the directory of the current document.  The name of the current
document needs to be passed to the external program.  You can specify
where and how this is done:
   
     %**N will be replaced with the filename without extension
     %**F will be replaced with the filename including the extension

Most likely, all you need to change here is the path to GSView.

#9 is the command to print a DVI file.  The syntax is the same as with
#6...8.  The command may be left empty; the corresponding menu item
will be suppressed then.  This makes sense if you prefer to print via
the graphical user interface of dvipm or GSview only.

Item #10 must reflect the name of the command to run dvips on your TeX
system.  The command name may refer to a binary program or to a CMD
script, and you may omit the extension.  Most likely, you need not
change the initial setting "dvips".

#11 is the name of the command to convert from PostScript to PDF.  The
default is "ps2pdf".  You might want to change that to "ps2pdf12" or
whatever is suitable for your needs.

Once you have checked and -- if necessary -- corrected all settings,
click on OK; the settings will be saved and applied immediately.



========================================================================
                    II. Using the TeX Front End
========================================================================


1. The TeX menu
---------------
The TeX Front End adds a new menu named "TEX" to the EPM editor.  The
items of this menu serve to execute the TeX-specific actions and to
configure the TeX Front End.  Menu items are `grayed out', when they are
not applicable to the current file.

  TEX runs TeX on the current document.  The document will be saved if
  necessary.

  TEX-DVIPS runs TeX and will immediately convert the resulting DVI file
  to Postscript then.

  LOCATE NEXT ERROR analyzes the log file of the last TeX run and marks
  the location of the next error in the related source file.  In case
  the location of the error cannot be determined, the log file will be
  displayed.

  VIEW LOG FILE switches to the log file of the last TeX run.  Executing
  this action while the log file is already being displayed will reset
  the error browsing facility to the first TeX error.

  START DVI VIEWER starts the DVI previewing program.

  START PS VIEWER starts a Postscript previewing program.

  START PDF VIEWER starts a PDF previewing program.

  PRINT DVI FILE prints the current document.  An entry window will pop
  up, where you can specify extra options, e.g., to print certain pages
  only.

  DVIPS executes "dvips <filename>".  In contrast to "TEX-DVIPS,
  additional options for dvips can be specified interactively and will
  be added to the command before the <filename>.

  PS2PDF executes "ps2pdf <filename>", i.e.  the well-known script to
  turn .dvi into .pdf.  Additional options for the ps2pdf script can be
  entered in a window that will pop up then.

  MASTER FILE SUPPORT toggles the `master file' facility (see below,
  section 4).

  SETTINGS opens the configuration window.  Settings changed here are
  saved immediately.

Two further meu items are added to the existing FILE and COMMAND menus
of the EPM (unless you are using an EPM version with a non-standard
menu; in this case they appear in the TeX menu).
  

  FOLDER opens the directory of the current file as a WPS folder.

  SHELL opens an OS/2 command shell window in the directory of the
  current file.  This may be useful to manually run auxiliary programs.

Please, note that the menu items for the previewing programs and for the
OS/2 command shell will always open a new window; they do NOT bring 
to the foreground a window which has already been created. 



2. The hot-keys                                
---------------
Various actions can be executed via the keyboard, too:
TEX    : Ctrl-F9
TEX/PS : Ctrl-F10
ERROR  : Ctrl-F11
LOG    : Ctrl-F12
dvips  : Ctrl-V



3. Using various formats and applications
-----------------------------------------
The default TeX format is LaTeX, unless a format is specified in the
first line of the document, using the following syntax, e.g. for the
"texinfo" format:

% format: texinfo

This is compatible with E. Mattes' REXX program "texit.cmd" and other
TeX IDEs.  Alternatively, the EPM TeX Front End understands the teTeX
syntax, too:

%&texinfo

The default format can be changed in the configuration window.

Actually, the EPM will simply execute a program or batch script with the
given name, i.e.  specifying the format "foo" makes the EPM execute the
command "foo" with the name of the current document as the argument.  
|
|  The only exception is the format "plain", which is automatically
|  translated into calling of a program named "tex"
|
In order to run VTeX/2 from the TeX Front End, you just have to specify
the name of the appropriate batch file as the document format, e.g.:

% format: vlatex

You may also change the default format to "vlatex".



4. Master file support
----------------------
Long TeX documents are typically spread over several files and included
into a common "master" file using \input or \include commands.  To
provide special support for this way of handling multi-file documents,
you have to turn on the "Master file support" via the menu.  TeXing a
document will then cause all dependent files in the same EPM window
(edit ring) to be checked for modification, and they will be saved if
necessary.  "Dependent files" are those which are included via \input or
\include commands.  Nested dependencies are not recognized, however.

Each of the dependent files should, in its first line, indicate the
corresponding master file, for instance

% master: main

In this example the master file is "main.tex".  Then TeX, the printer
driver, the previewing programs etc.  can be called while editing one of
the dependent files, and the main document will be used for the action.

Disabling the master file support is not required when TeXing "simple"
documents.  With long text files, however, it may slow down the TeX
Front End unnecessarily.  Master File Support should also be disabled
when editing documented LaTeX sources containing the commands \input or
\include within their code sections.



5. TeXing a marked region of a file                 
-----------------------------------
It is possible to process a marked region of a file only, as opposed to
formatting the complete file.  When TeXing is requested while there is a
marked region in the file being edited, the EPM will ask you whether to
compile the whole document or the marked region only.  This works with
standard (CUA) marking mode as well as with the "advanced" marking mode,
but not with block marks.

The marked region will be combined with the preamble (or header) of the
document, i.e.  the lines from the beginning of the file up to one
containing "\begin{document}" or "%**end of header".  If the string
"\begin{document}" is found, the corresponding "\end{document}" will be
added to the end of the text to be formatted; otherwise the text gets
terminated with "\bye".  The action stops with an appropriate error
message, if the end of the header cannot be located.  Please, note that
a temporary file is created with the name of the current document and
the extension ".___".

From version 5.4 on, there are no more restrictions regarding the use of
the error.browsing facility, when a marked region is processed.


6. LaTeX syntax assist
----------------------
* Environments:  Typing <return> in a line containing the header of an
arbitrary environment, i.e.  \begin{...}, causes the corresponding
\end{...} statement to be added.  (Type Ctrl-<return> to suppress
expansion).  In the new line the cursor is indented appropriately,
except for the environments "document", "verbatim" and "macrocode".
Furthermore, entering "\begin{macrocode}" will cause the current line to
be replaced with
%    \begin{macrocode}

%    \end{macrocode}

Additionally, \[ is recognized as an environment, too.
                                                     
* Keywords:  The following commands and keywords are completed when
entering <space> after the first three characters.  (Type Ctrl-<space>
to suppress expansion.)
   \be -> \begin{}
   equ -> equation
   eqn -> eqnarray
   \fr -> \frac{}{}
   \(  -> \( \)
   \la -> \label{}
   \re -> \ref{}
   \pa -> \pageref{}
   \ci -> \cite{}
   \fo -> \footnote{}

* Accelerator keys (the vertical bar indicates the position of the 
cursor):
   Alt-a -> eqnarray|
   Alt-b -> \begin{|}
   Alt-c -> \cite{|}
   Alt-d -> description|
   Alt-e -> equation|
   Alt-f -> \frac{|}{}
   Alt-h -> \hspace*{|}
   Alt-i -> \item|
   Alt-j -> itemize|
   Alt-k -> tabular|
   Alt-l -> \label{|}
   Alt-m -> \mbox{|}
   Alt-n -> enumerate|
   Alt-q -> equation|
   Alt-r -> \ref{|}
   Alt-s -> \sqrt{|}
   Alt-v -> \vspace*{|}
   Alt-w -> verbatim|
    {    -> {|}
    $    -> $|$ 

Completion of environments and keywords is usually active with documents
and style files, unless you disable the "expand" facility of the Editor.

The accelerator keys are optional.  Their behavior can be be toggled via
the configuration window.  The initial setting is "off".  Caution:
Enabling/disabling these keys does not affact files that are already
loaded.  The keys are compatible with EPMTeX 3.1.



7. Syntax Highlighting
----------------------
TeX syntax highlighting can be toggled via item 12 in the configuration
window.  Caution:  Files that are already loaded are not affected.  The
initial setting is "off".  

Syntax highlighting is controlled by the file EPMKWDS.TEX which does not
belong to the TeX Front End; it has been adopted from a free EPM
distributuion (so -- please -- don't blame _me_ for misisng keywords or
ugly colors ;-)




========================================================================
                      III  Advanced configuration
========================================================================


1. File types
-------------
Certain features of the TeX Front End are enabled according to the type
( = extension ) of the current file:

Running TeX is possible for file types defined as TeX documents;
initially these are TEX, DTX and INS.

Syntax assist and highlighting should be provided when editing style
files, too.  Initially, the types STY and CLS are recognized.

The configuration window provides items for editing the file types,
which are recognized as documents or style files.  The file types must
be entered _without_ the leading dot.  



2. External programs
--------------------
Apart from the items for TeXing, previewing and printing, there are four
user-definable commands, which can be run from the menu.  They are set
up using a configuration file, rather than the SETTINGS menu.  Unless
you have got a configuration file from a previous version of the TeX
Front End already, you should start with a simple example.  Copy the
following four lines to a file named "tfe.cfg" in the EPM directory:

  USER1_CMD       = start /n /f bibtex %**N
  USER1_EXT       = .aux
  USER1_MENU_TEXT = BibTeX
  USER1__MSG      = Run BibTeX on current document

Having finished the configuration file "tfe.cfg", shut down the editor,
open an OS/2 window in the EPM directory and run the command "tfconfig"
to transfer the information from the file into the EPM.  After
restarting the EPM you should see an additional item in the VTeX menu,
labelled "BibTeX".  Now, what do the above lines mean in detail?

USER1_CMD is the EPM command to be executed from the first menu item.
The EPM starts external programs using the "start" command, which you
should know from the OS/2 command prompt.  A binary program is launched
using the option /n, whereas a batch file is executed using /c.  All
programs will be executed in the directory of the current document.

Usually the name of the current document needs to be passed to the
external program.  You can specify where and how this is done via the
strings "%**N" and "%**F".  When the command is actually executed, these
strings are replaced as follows:

  %**N+ ->  file name without extension
  %**F+ ->  file name with extension

Certain commands need to be given extra options manually, when they are
launched.  If you include a string in square brackets to your command,
then a window will pop up when the program is started and you will be
asked to enter additional options:  "Enter extra options for <string>".
For instance, when the makeindex program is declared as

  USER1_CMD = start /n /f makeindex [makeindex] %**N

then EPM will prompt: 

  "Enter extra options for makeindex"
  
The information you enter will be included into the command string just
in the place of the square brackets.  

|  Note that the same syntax, including the pop-up options, applies also
|  to the commands for previoewing DVI printing, see PartI, section 2.


If USER1_EXT is defined, running the first user-definable program
requires the file with the given extension to exists.  E.g., BibTeX can
be run only if the .aux file exists.  In case the USER1_EXT statement is
omitted, starting of the program will not depend on the presence of a
certain file.

USER1_MENU_TEXT is the title of the corresponding menu item.  A tilde in
this string makes the following character act as a menu shortcut.

USER1__MSG is an (optional) menu prompt.

Up to four menu items and related commands can be declared by following the 
above model.  Just add their declarations to the file tfe.cfg  and 
replace the
"1" in the keywords with 2, 3 or 4.
Do not forget to run tfconfig after any change to the configuration 
file; otherwise the change will never come into effect
Notice that an existing entry cannot be deleted by simply omitting it 
from the next "generation" of tfe.cfg.  You must supply an 
"empty" value, e.g., 

 USER1_EXT=

instead.



3. The configuration tool TFCONFIG
----------------------------------
The program TFCONFIG serves not only to bring the information from the
configuration file tfe.cfg into the EPM.  Here is a summary of the
TFCONFIG invocation:

        TFCONFIG [file] [/option]

Available options are:

        N  list contents of configuration file only
        U  read settings from configuration file and write them
           to the TeX Front End 
        V  view current settings of the TeX Front End
        D  delete all settings from the EPM

/U is the default option.  In case no FILE is specified, settings are
read from a file named "tfe.cfg" in the current directory.  Any filename
is ignored, if /V or /D are requested.



4. The Icon
-----------
An icon TEXFE.ICO which may suit an "Editor for TeX", is part of the
distribution and can be found in the directory of the EPM.



========================================================================
                                Appendix
========================================================================


Known bugs
----------
* The Alt-T key always opens the TeX menu, regardless of the global
setting of "Menu accelerators" for the editor.
  
* The name of a TeX file is required to have an extension.

* The master file dependency system recognizes only one \input or 
\include command per line.

* A drive letter in a "% master" statement is not always processed
properly.  (There should, however, be no real need for specifying a
drive letter there.)

* The error searching facility may occasionally display a wrong source 
file or none at all.

* The focus does not always return to the EPM window, after TeX or 
another external program has finished.



Distribution and support
------------------------
For the current version of this software see

  ftp://dante.ctan.org/tex-archive/systems/os2/epmtfe/

or any other CTAN host.

In case you encounter any problems upon installing or using the TeX 
Front End, please, contact the author:

  Walter Schmidt <epmtfe@gmx.net>



Thanks to ...
-------------
...  Jon Hacker and Rodney Korte for providing the program EPMTeX and
for the permission to use large parts of their source code.  Without the
model EPMTeX I would never have been able to write the TeX Front End.
Wonkoo Kim suggested and created the configuration menu, and he found 
various bugs.  Andreas Schnellbacher provided many of the new features 
introduced with version 5.


== finis
