======================================================================== The EPM TeX Front End -- an integrated TeX environment for OS/2 ======================================================================== Version 3.0 2000-04-19 The EPM TeX Front End is an additional module for the OS/2 "Enhanced Editor" (EPM). It turns the EPM into an integrated (em)TeX environment, providing (La)TeXing, previewing, printing etc. from within the editor. 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 a module which can be added to an existing EPM. Alternatively you can merge its E language source code into a customized EPM version; see the file source.zip of the distribution. CONTENTS: Part I: Installing the TeX Front End 1. Updating 2. Installing and configuring 3. Including additional programs 4. Installing a toolbar 5. TeX Front End without a menu 6. The Icon 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 8. File types Appendix Using the TeX Front End with VTeX/2 The configuration tool TFCONFIG Known bugs Distribution and support Credits ======================================================================== I. Installing the TeX Front End ======================================================================== 1. Updating ----------- In case a previous version of the TeX Front End has already been installed, all files from the archive tfe.zip (English version) of the distribution are to be unpacked to your EPM directory -- except for the configuration file tfe.cfg and any .BMP files you have changed in the meanwhile! If the editor is running, you must shut down and restart it. In case you want to make use of PDF documents in conjunction with TeX, you should add a suitable VIEWPDF_CMD entry (see below, section 2) to your configuration file tfe.cfg. The file NEWS lists all changes applied from one version to the next. 2. Installing and configuring ----------------------------- Before installing the TeX Front End, please check the following: * You must have installed the `Enhanced Editor' EPM v6.03b, which is shipped with Warp4 (_not_ Warp3) or can be obtained (free!) from various sources, e.g. . * You must have installed a TeX system, e.g. emTeX or emTeX/TDS. * You must have installed dvips and Ghostscript/GSView (only for Postscript conversion, previewing or printing) Installing the EPM TeX Front End requires 3 steps to be performed: 1) Copying the necessary files to your system. 2) Editing the configuration file tfe.cfg and configuring the TeX Front End via this file. 3) Making the EPM import the TeX module. 1) Unpack the files from the archive tfe.zip of the distribution 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. 2) Now you will have to check - and perhaps edit - the configuration file file "tfe.cfg" in the EPM directory. The initial information in this file should already suit a standard emTeX system: # the command to start a DVI viewer: VIEW_CMD = start /c /f vp.cmd %**N # # the command to start a PS viewer: VIEWPS_CMD = start /n /f c:\gstools\gsview\gvpm.exe %**N.ps # # the command to start a PDF viewer: VIEWPDF_CMD = start /n /f c:\gstools\gsview\gvpm.exe %**N.pdf # # the command to print a document: PRINT_CMD = start /c /f prthpljh.cmd %**N [dvihplj] # # the 1st user-definable program, here BiBTeX: USER1_CMD = start /n /f bibtex32 %**N USER1_EXT = .aux USER1_MENU_TEXT = BibTeX USER1__MSG = Run BibTeX on current document # # the OS/2 commands to execute the TeX formats plain and latex # the default is .cmd: LATEX = latex2e.cmd PLAIN = tex.cmd # # the name of the dvips program, defaults to dvips: DVIPS_EXEC = dvips32 In this file everything following a # is treated as a comment. All the information is contained in lines showing the structure KEYWORD = VALUE The _CMD keywords specify EPM commands. 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 run in the directory of the current document. Usually the name of the current document need 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 Certain commands need a facility for extra options to be added 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 " The information you enter will be included into the command string just in the place of the square brackets. With a printer driver you can, e.g., specify the range of pages to be printed. The EPM TeX Front End will call a special shell script for each TeX format. The command name is made up by adding ".CMD" to the name of the format. The format "FOO", e.g., will be called as "FOO.CMD". The command for printing can be omitted; the corresponding menu item is suppressed then. This makes sense, if you prefer to print via the graphical user interface of dvipm or GSview only. *** new in v2.4 *** PDF previewing (keyword VIEW_PDF) is available since v2.5 only! *** new in v2.5 *** Using the keywords "PLAIN" and "LATEX" one can specify other commands to be executed for these two formats, as it is done in the above configuration file with respect to the standard emTeX settings. (In fact it is possible to assign a special command to _any_ format, but future versions of the TeX Front End may support plain and latex only. *** changed in v2.4 *** The dvips program can be of type .exe or .cmd. As on the command line, the file type need not be indicated. *** changed in v2.4 *** ( In case you have installed the emTeX/TDS distribution, as opposed to the original emTeX system, you should replace the above file tfe.cfg with the one that comes with emTeX/TDS. This file does not need editing, except for the entry VIEWPS_CMD, which is to be changed, if you have installed Ghostscript/GSView on a different drive than C. ) Now you have to change to the EPM directory and run the command TFCONFIG which will transfer the information from tfe.cfg to the binary EPM configuration file. Any changes to tfe.cfg will become effective only after repeating this step! CAUTION: After an entry ( KEYWORD = VALUE ) has been transferred to the EPM using TFCONFIG, you cannot delete it by simply omitting it from the next "generation" of tfe.cfg. You must supply an "empty" value, e.g. "LATEX =", instead. 3) Finally the EPM must be configured to link the TeX Front End at startup. Include the line (the quotes are part of the information) 'link texfe.ex' to the REXX profile (file profile.erx in the EPM directory) and enable the EPM option "REXX profile". A sample REXX profile (profile.smp) containing various useful startup actions is contained in the EPM directory of the distribution. After closing and restarting the EPM the TeX Front End will be ready. 3. Including additional programs -------------------------------- Apart from the items for TeXing, previewing and printing there are four user-definable commands, which can be run from the menu. Initially the configuration file defines only BibTeX to be one of them: USER1_CMD = start /n /f bibtex %**N USER1_EXT = .aux USER1_MENU_TEXT = BibTeX USER1__MSG = Run BibTeX on current document The keywords for the commands to be executed USERn_CMD, n=1...4. It is not only possible to launch external programs via "start"; any valid EPM command can be specified here! The command will be executed in the directory of the current document. If USERn_EXT is defined, then running the program # n requires the file with the given extension to exists. E.g., BibTeX can be run only if the .aux file exists. USERn_MENU_TEXT is the title of the corresponding menu item. A tilde ~ in this string makes the following character act as a menu shortcut. USERn_MSG is an (optional) prompt, i.e. a short info about what's going to happen, which is displayed in the status line. You can add further programs simply by following the above model; do not forget to run tfconfig after editing tfe.cfg! In case a toolbar is used, appropriate icons and titles for the USER buttons should be provided. The icons displayed here are contained in the files TEX____1.BMP ... TEX____4.BMP; they are searched for in the EPM directory. 4. Installing a toolbar ----------------------- The TeX Front End may be controlled via a toolbar, too. On the page `Toolbar' of the EPM settings notebook you have to inport the toolbar from the file texfe.bar, make this toolbar the current one and enable toolbar display. 5. TeX Front End without a menu ------------------------------- In case you encounter any problems with the menu, you may compile a toolbar-only version from the sources; see the file SOURCE\compile.txt. Please, contact the author if you need this but cannot compile E code. 6. The Icon ----------- An icons TEXFE.ICO which may suit an `Editor for TeX', is part of the distribution and can be found in the directory of the EPM. ======================================================================== II. Using the TeX Front End ======================================================================== 1. The TeX menu --------------- 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 source file. In case the line number of the error cannot be determined or is not found in the source file, 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 ". In contrast to "TEX-DVIPS, additional options for dvips can be specified interactively and will be added to the command before the . BIBTEX runs BibTeX on the current document. SETTINGS opens the configuration window. Settings changed here are saved immediately. SHELL opens an OS/2 command shell window in the directory of the current file. FOLDER opens the directory of the current file as a WPS folder. 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 a window to the foreground which has been created before. 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. LaTeX and other formats -------------------------- 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 `plain' format: % format: plain This is compatible with E. Mattes' REXX program "texit.cmd" and other TeX IDEs. The default format (LaTeX) can be changed in the configuration window. 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 configuration menu. Then TeXing a document will 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, however, not recognized. Each of the dependent files should, in its first line, indicate the corresponding master file: % 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. This feature is enabled if TeXing is requested while there is a marked region in the file being edited. You will be asked to confirm that only the marked region is to be processed. *** new in v2.4 *** This works with standard (CUA) marking mode as well as with the "advanced" marking mode; block marks can, however, not be processed. 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". In case the string "\begin{document}" is found, the coresponding "\end{document}" will be added to the end of the text to be formatted, otherwise "\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 ".___". The "Error" menu item will display the log file (neither the source file nor the temporary file), in case a marked region has been processed before. 6. LaTeX syntax assist ---------------------- *** changed in v2.4 *** * Environments: Typing in a line containing the header of an arbitrary environment, i.e. \begin{...}, causes the corresponding \end{...} statement to be added. (Type Ctrl- 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 after the first three characters. (Type Ctrl- 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 will only become effective after changing the current file. The keys are compatible with EPMTeX 3.1. 7. Syntax Highlighting ---------------------- TeX syntax highlighting can be toggled via the configuration window, too. Caution: Files 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, but is part of the OS/2 EPM package. 8. 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 this is ".tex" only . *** changed with v3.0 *** Syntax assist and highlighting should be provided when editing style files, too. Initially, only the type ".sty" is 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. ======================================================================== Appendix ======================================================================== Using the TeX Front End with VTeX/2 *** new in v2.5 *** ----------------------------------- In order to run VTeX 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 See section 3 above! You may also change the default format to "vlatex". Starting with version 2.5, the TeX Front End will also recognize the format of VTeX's log files, so that the menu item LOCATE NEXT ERROR works as expected. The configuration tool TFCONFIG ------------------------------- In addition to initializing the TeX Font End, the configuration program TFCONFIG may also be used for other purposes. 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 the configuration file .\tfe.cfg. A given filename is ignored, if /V or /D is requested. Known bugs ---------- * The Alt-T key will always open the TeX menu, regardless of the setting of `Menu accelerators'. * The name of a TeX file is required to have an extension. * The master file dependency system recognizes only one \input or \include command in a 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 sometime display a wrong source file or none at all. 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 Please, obtain my email address from the latest version of this document! 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. Finally ... ----------- ... I would like to apologize for my bad English. English is not my native language. Suggestions for improving this document and the messages displayed by the program are welcome.