home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 5 Edit / 05-Edit.zip / eptxfn30.zip / readme.txt < prev    next >
Text File  |  2002-05-06  |  22KB  |  597 lines
  1. ========================================================================
  2.     The EPM TeX Front End -- an integrated TeX environment for OS/2
  3. ========================================================================
  4.                                                              Version 3.0
  5.                                                               2000-04-19
  6.  
  7.  
  8. The EPM TeX Front End is an additional module for the OS/2 "Enhanced
  9. Editor" (EPM).  It turns the EPM into an integrated (em)TeX environment,
  10. providing (La)TeXing, previewing, printing etc. from within the editor.
  11. Special features are:
  12.  
  13.   - Optional TeXing of a marked region of a file
  14.   - TeX errors are marked and explained in the source code window.
  15.   - Postscript support (dvips conversion on-the-fly)
  16.   - Support for documents spread over multiple files
  17.   - Optional LaTeX syntax assist
  18.   - OS/2 shell and WPS interface
  19.  
  20. The TeX Front End is a module which can be added to an existing EPM.
  21. Alternatively you can merge its E language source code into a customized
  22. EPM version; see the file source.zip of the distribution.
  23.  
  24.  
  25. CONTENTS:
  26.  
  27. Part I: Installing the TeX Front End
  28.  
  29. 1. Updating
  30. 2. Installing and configuring
  31. 3. Including additional programs
  32. 4. Installing a toolbar
  33. 5. TeX Front End without a menu
  34. 6. The Icon
  35.  
  36. Part II: Using the TeX Front End
  37.  
  38. 1. The TeX menu
  39. 2. The hot-keys                                
  40. 3. LaTeX and other formats
  41. 4. Master file support
  42. 5. TeXing a marked region of a file                 
  43. 6. LaTeX syntax assist
  44. 7. Syntax Highlighting
  45. 8. File types
  46.  
  47. Appendix
  48.  
  49.    Using the TeX Front End with VTeX/2
  50.    The configuration tool TFCONFIG
  51.    Known bugs
  52.    Distribution and support
  53.    Credits
  54.    
  55.  
  56. ========================================================================
  57.                     I. Installing the TeX Front End
  58. ========================================================================
  59.  
  60.  
  61. 1. Updating
  62. -----------
  63. In case a previous version of the TeX Front End has already been
  64. installed, all files from the archive tfe.zip (English version) of the
  65. distribution are to be unpacked to your EPM directory -- except for the
  66. configuration file tfe.cfg and any .BMP files you have changed in the
  67. meanwhile!  If the editor is running, you must shut down and restart it.
  68.  
  69. In case you want to make use of PDF documents in conjunction with TeX,
  70. you should add a suitable VIEWPDF_CMD entry (see below, section 2) to
  71. your configuration file tfe.cfg.
  72.  
  73. The file NEWS lists all changes applied from one version to the next.
  74.  
  75.  
  76.  
  77. 2. Installing and configuring
  78. -----------------------------
  79. Before installing the TeX Front End, please check the following:
  80.  
  81.    * You must have installed the `Enhanced Editor' EPM v6.03b, which is
  82.      shipped with Warp4 (_not_ Warp3) or can be obtained (free!) from 
  83.      various sources, e.g.
  84.      <ftp://ftp.leo.org/pub/comp/os/os2/leo/editors/epm603b.zip>.
  85.    * You must have installed a TeX system, e.g. emTeX or emTeX/TDS.
  86.    * You must have installed dvips and Ghostscript/GSView (only for
  87.      Postscript conversion, previewing or printing)
  88.  
  89. Installing the EPM TeX Front End requires 3 steps to be performed:
  90.  
  91.    1) Copying the necessary files to your system.
  92.    2) Editing the configuration file tfe.cfg and
  93.       configuring the TeX Front End via this file.
  94.    3) Making the EPM import the TeX module.
  95.  
  96.  
  97.    1) Unpack the files from the archive tfe.zip of the distribution to
  98.    the directory where the EPM resides on your system (the "EPM
  99.    directory").  Usually this should be the directory OS2\APPS of the
  100.    boot drive.
  101.    
  102.    
  103.    2) Now you will have to check - and perhaps edit - the configuration
  104.    file file "tfe.cfg" in the EPM directory.  The initial information in
  105.    this file should already suit a standard emTeX system:
  106.    
  107.    # the command to start a DVI viewer:
  108.    VIEW_CMD        = start /c /f vp.cmd %**N
  109.    #
  110.    # the command to start a PS viewer:
  111.    VIEWPS_CMD      = start /n /f c:\gstools\gsview\gvpm.exe %**N.ps
  112.    #
  113.    # the command to start a PDF viewer:
  114.    VIEWPDF_CMD     = start /n /f c:\gstools\gsview\gvpm.exe %**N.pdf
  115.    #
  116.    # the command to print a document:
  117.    PRINT_CMD       = start /c /f prthpljh.cmd %**N [dvihplj]
  118.    #
  119.    # the 1st user-definable program, here BiBTeX:
  120.    USER1_CMD       = start /n /f bibtex32 %**N
  121.    USER1_EXT       = .aux
  122.    USER1_MENU_TEXT = BibTeX
  123.    USER1__MSG      = Run BibTeX on current document
  124.    #
  125.    # the OS/2 commands to execute the TeX formats plain and latex
  126.    # the default is <format>.cmd:
  127.    LATEX           = latex2e.cmd
  128.    PLAIN           = tex.cmd
  129.    #
  130.    # the name of the dvips program, defaults to dvips:
  131.    DVIPS_EXEC      = dvips32
  132.    
  133.    In this file everything following a # is treated as a comment.  All
  134.    the information is contained in lines showing the structure
  135.    
  136.    KEYWORD = VALUE
  137.    
  138.    The _CMD keywords specify EPM commands.  The EPM starts external
  139.    programs using the "start" command, which you know from the OS/2
  140.    command prompt.  A binary (.exe) program is launched by "start /n",
  141.    whereas a batch file (.cmd) must is executed via "start /c".  All 
  142.    programs will run in the directory of the current document.
  143.    
  144.    Usually the name of the current document need to be passed to the
  145.    external program.  You can specify where and how this is done:
  146.    
  147.    %**N will be replaced with the filename without extension
  148.    %**F will be replaced with the filename including the extension
  149.    
  150.    Certain commands need a facility for extra options to be added
  151.    manually when they are launched.  If you include a string in square
  152.    brackets to your command, then a window will pop up when the program
  153.    is started and you will be asked to enter additional options:
  154.    
  155.        "Enter extra options for <string between the brackets>"
  156.    
  157.    The information you enter will be included into the command string
  158.    just in the place of the square brackets.  With a printer driver you
  159.    can, e.g., specify the range of pages to be printed.
  160.  
  161.    The EPM TeX Front End will call a special shell script for each TeX
  162.    format.  The command name is made up by adding ".CMD" to the name of
  163.    the format.  The format "FOO", e.g., will be called as "FOO.CMD".
  164.    
  165.    The command for printing can be omitted; the corresponding menu item
  166.    is suppressed then.  This makes sense, if you prefer to print via the
  167.    graphical user interface of dvipm or GSview only. *** new in v2.4 ***
  168.    
  169.    PDF previewing (keyword VIEW_PDF) is available since v2.5 only!
  170.                                                      *** new in v2.5 ***
  171.  
  172.    Using the keywords "PLAIN" and "LATEX" one can specify other commands
  173.    to be executed for these two formats, as it is done in the above
  174.    configuration file with respect to the standard emTeX settings.  (In
  175.    fact it is possible to assign a special command to _any_ format, but
  176.    future versions of the TeX Front End may support plain and latex
  177.    only.                                         *** changed in v2.4 ***
  178.    
  179.    The dvips program can be of type .exe or .cmd.  As on the command 
  180.    line, the file type need not be indicated.    *** changed in v2.4 ***  
  181.  
  182.    ( In case you have installed the emTeX/TDS distribution, as opposed
  183.    to the original emTeX system, you should replace the above file
  184.    tfe.cfg with the one that comes with emTeX/TDS.  This file does not
  185.    need editing, except for the entry VIEWPS_CMD, which is to be
  186.    changed, if you have installed Ghostscript/GSView on a different 
  187.    drive than C. )
  188.    
  189.    Now you have to change to the EPM directory and run the command
  190.    TFCONFIG which will transfer the information from tfe.cfg to the
  191.    binary EPM configuration file.  Any changes to tfe.cfg will become
  192.    effective only after repeating this step!
  193.    
  194.    CAUTION:  After an entry ( KEYWORD = VALUE ) has been transferred to
  195.    the EPM using TFCONFIG, you cannot delete it by simply omitting it
  196.    from the next "generation" of tfe.cfg.  You must supply an "empty"
  197.    value, e.g. "LATEX =", instead.
  198.    
  199.    
  200.    3) Finally the EPM must be configured to link the TeX Front End at
  201.    startup.  Include the line (the quotes are part of the information)
  202.    
  203.            'link texfe.ex'
  204.    
  205.    to the REXX profile (file profile.erx in the EPM directory) and
  206.    enable the EPM option "REXX profile".
  207.  
  208.    A sample REXX profile (profile.smp) containing various useful startup
  209.    actions is contained in the EPM directory of the distribution.
  210.    
  211. After closing and restarting the EPM the TeX Front End will be ready.
  212.  
  213.  
  214.  
  215. 3. Including additional programs
  216. --------------------------------
  217.  
  218. Apart from the items for TeXing, previewing and printing there are four
  219. user-definable commands, which can be run from the menu.  Initially the
  220. configuration file defines only BibTeX to be one of them:
  221.  
  222. USER1_CMD       = start /n /f bibtex %**N
  223. USER1_EXT       = .aux
  224. USER1_MENU_TEXT = BibTeX
  225. USER1__MSG      = Run BibTeX on current document
  226.  
  227. The keywords for the commands to be executed USERn_CMD, n=1...4.  It is
  228. not only possible to launch external programs via "start"; any valid EPM
  229. command can be specified here!  The command will be executed in the
  230. directory of the current document.
  231.  
  232. If USERn_EXT is defined, then running the program # n requires the file
  233. with the given extension to exists.  E.g., BibTeX can be run only if the
  234. .aux file exists.
  235.  
  236. USERn_MENU_TEXT is the title of the corresponding menu item.  A tilde ~
  237. in this string makes the following character act as a menu shortcut.
  238.  
  239. USERn_MSG is an (optional) prompt, i.e. a short info about what's going 
  240. to happen, which is displayed in the status line.
  241.  
  242. You can add further programs simply by following the above model; do not
  243. forget to run tfconfig after editing tfe.cfg!
  244.  
  245. In case a toolbar is used, appropriate icons and titles for the USER
  246. buttons should be provided.  The icons displayed here are contained in
  247. the files TEX____1.BMP ...  TEX____4.BMP; they are searched for in the
  248. EPM directory.
  249.  
  250.  
  251.  
  252. 4. Installing a toolbar
  253. -----------------------
  254. The TeX Front End may be controlled via a toolbar, too.  On the page
  255. `Toolbar' of the EPM settings notebook you have to inport the toolbar
  256. from the file texfe.bar, make this toolbar the current one and enable
  257. toolbar display.
  258.  
  259.  
  260.  
  261. 5. TeX Front End without a menu
  262. -------------------------------
  263. In case you encounter any problems with the menu, you may compile a
  264. toolbar-only version from the sources; see the file SOURCE\compile.txt.
  265. Please, contact the author if you need this but cannot compile E code.
  266.  
  267.  
  268.  
  269. 6. The Icon
  270. -----------
  271. An icons TEXFE.ICO which may suit an `Editor for TeX', is part of the
  272. distribution and can be found in the directory of the EPM.
  273.  
  274.  
  275.  
  276.  
  277. ========================================================================
  278.                     II. Using the TeX Front End
  279. ========================================================================
  280.  
  281.  
  282. 1. The TeX menu
  283. ---------------
  284. TEX runs TeX on the current document.  The document will be saved if 
  285. necessary.
  286.  
  287. TEX-DVIPS runs TeX and will immediately convert the resulting DVI file 
  288. to Postscript then.
  289.  
  290. LOCATE NEXT ERROR analyzes the log file of the last TeX run and marks
  291. the location of the next error in the source file.  In case the line
  292. number of the error cannot be determined or is not found in the source
  293. file, the log file will be displayed.
  294.  
  295. VIEW LOG FILE switches to the log file of the last TeX run.  Executing
  296. this action while the log file is already being displayed will reset the
  297. error browsing facility to the first TeX error.
  298.  
  299. START DVI VIEWER starts the DVI previewing program.
  300.  
  301. START PS VIEWER starts a Postscript previewing program.
  302.  
  303. START PDF VIEWER starts a PDF previewing program.
  304.  
  305. PRINT DVI FILE prints the current document.  An entry window will pop
  306. up, where you can specify extra options, e.g., to print certain pages
  307. only.
  308.  
  309. DVIPS executes "dvips <filename>".  In contrast to "TEX-DVIPS,
  310. additional options for dvips can be specified interactively and will be
  311. added to the command before the <filename>.
  312.  
  313. BIBTEX runs BibTeX on the current document.
  314.  
  315. SETTINGS opens the configuration window.  Settings changed here are
  316. saved immediately.
  317.  
  318. SHELL opens an OS/2 command shell window in the directory of the current
  319. file.
  320.  
  321. FOLDER opens the directory of the current file as a WPS folder.
  322.  
  323. Please, note that the menu items for the previewing programs and for the
  324. OS/2 command shell will always open a new window; they do NOT bring 
  325. a window to the foreground which has been created before. 
  326.  
  327.  
  328.  
  329. 2. The hot-keys                                
  330. ---------------
  331. Various actions can be executed via the keyboard, too:
  332. TEX    : Ctrl-F9
  333. TEX/PS : Ctrl-F10
  334. ERROR  : Ctrl-F11
  335. LOG    : Ctrl-F12
  336. dvips  : Ctrl-V
  337.  
  338.  
  339.  
  340. 3. LaTeX and other formats
  341. --------------------------
  342. The default TeX format is LaTeX, unless a format is specified in the
  343. first line of the document, using the following syntax, e.g. for the
  344. `plain' format:
  345.  
  346. % format: plain
  347.  
  348. This is compatible with E. Mattes' REXX program "texit.cmd" and other
  349. TeX IDEs.
  350.  
  351. The default format (LaTeX) can be changed in the configuration window.
  352.  
  353.  
  354.  
  355. 4. Master file support
  356. ----------------------
  357. Long TeX documents are typically spread over several files and included
  358. into a common "master" file using \input or \include commands.  To
  359. provide special support for this way of handling multi-file documents,
  360. you have to turn on the "Master file support" via the configuration
  361. menu.  Then TeXing a document will cause all dependent files in the same
  362. EPM window (edit ring) to be checked for modification, and they will be
  363. saved if necessary.  "Dependent files" are those which are included via
  364. \input or \include commands.  Nested dependencies are, however, not
  365. recognized.
  366.  
  367. Each of the dependent files should, in its first line, indicate the
  368. corresponding master file:
  369.  
  370. % master: main
  371.  
  372. (In this example the master file is "main.tex".)  Then TeX, the printer
  373. driver, the previewing programs etc. can be called while editing one of 
  374. the dependent files, and the main document will be used for the action.
  375.  
  376. Disabling the master file support is not required when TeXing "simple"
  377. documents.  With long text files, however, it may slow down the TeX
  378. Front End unnecessarily.  Master File Support should also be disabled
  379. when editing documented LaTeX sources containing the commands \input or
  380. \include within their code sections.
  381.  
  382.  
  383.  
  384. 5. TeXing a marked region of a file                 
  385. -----------------------------------
  386. It is possible to process a marked region of a file only, as opposed to
  387. formatting the complete file.  This feature is enabled if TeXing is
  388. requested while there is a marked region in the file being edited.
  389. You will be asked to confirm that only the marked region is to be
  390. processed.
  391.                                                      *** new in v2.4 ***
  392. This works with standard (CUA) marking mode as well as with the
  393. "advanced" marking mode; block marks can, however, not be processed.
  394.  
  395. The marked region will be combined with the preamble (or header) of the
  396. document, i.e.  the lines from the beginning of the file up to one
  397. containing "\begin{document}" or "%**end of header".  In case the string
  398. "\begin{document}" is found, the coresponding "\end{document}" will be
  399. added to the end of the text to be formatted, otherwise "\bye".  The
  400. action stops with an appropriate error message, if the end of the header
  401. cannot be located.  Please, note that a temporary file is created with
  402. the name of the current document and the extension ".___".
  403.  
  404. The "Error" menu item will display the log file (neither the source file
  405. nor the temporary file), in case a marked region has been processed
  406. before.
  407.  
  408.  
  409.  
  410. 6. LaTeX syntax assist
  411. ----------------------                           *** changed in v2.4 ***
  412. * Environments:  Typing <return> in a line containing the header of an
  413. arbitrary environment, i.e.  \begin{...}, causes the corresponding
  414. \end{...} statement to be added.  (Type Ctrl-<return> to suppress
  415. expansion).  In the new line the cursor is indented appropriately,
  416. except for the environments "document", "verbatim" and "macrocode".
  417. Furthermore, entering "\begin{macrocode}" will cause the current line to
  418. be replaced with
  419. %    \begin{macrocode}
  420.  
  421. %    \end{macrocode}
  422.  
  423. Additionally, \[ is recognized as an environment, too.
  424.                                                      
  425. * Keywords:  The following commands and keywords are completed when
  426. entering <space> after the first three characters.  (Type Ctrl-<space>
  427. to suppress expansion.)
  428.    \be -> \begin{}
  429.    equ -> equation
  430.    eqn -> eqnarray
  431.    \fr -> \frac{}{}
  432.    \(  -> \( \)
  433.    \la -> \label{}
  434.    \re -> \ref{}
  435.    \pa -> \pageref{}
  436.    \ci -> \cite{}
  437.    \fo -> \footnote{}
  438.  
  439. * Accelerator keys (the vertical bar indicates the position of the 
  440. cursor):
  441.    Alt-a -> eqnarray|
  442.    Alt-b -> \begin{|}
  443.    Alt-c -> \cite{|}
  444.    Alt-d -> description|
  445.    Alt-e -> equation|
  446.    Alt-f -> \frac{|}{}
  447.    Alt-h -> \hspace*{|}
  448.    Alt-i -> \item|
  449.    Alt-j -> itemize|
  450.    Alt-k -> tabular|
  451.    Alt-l -> \label{|}
  452.    Alt-m -> \mbox{|}
  453.    Alt-n -> enumerate|
  454.    Alt-q -> equation|
  455.    Alt-r -> \ref{|}
  456.    Alt-s -> \sqrt{|}
  457.    Alt-v -> \vspace*{|}
  458.    Alt-w -> verbatim|
  459.     {    -> {|}
  460.     $    -> $|$ 
  461.  
  462. Completion of environments and keywords is usually active with documents
  463. and style files, unless you disable the "expand" facility of the Editor.
  464.  
  465. The accelerator keys are optional.  Their behavior can be be toggled
  466. via the configuration window.  The initial setting is "off".  Caution:
  467. Enabling/disabling these keys will only become effective after changing 
  468. the current file.  The keys are compatible with EPMTeX 3.1.
  469.  
  470.  
  471.  
  472. 7. Syntax Highlighting
  473. ----------------------
  474. TeX syntax highlighting can be toggled via the configuration window,
  475. too.  Caution:  Files already loaded are not affected.  The initial
  476. setting is "off".  Syntax highlighting is controlled by the file
  477. EPMKWDS.TEX which does not belong to the TeX Front End, but is part of
  478. the OS/2 EPM package.
  479.  
  480.  
  481.  
  482. 8. File types
  483. -------------
  484. Certain features of the TeX Front End are enabled according to the type
  485. ( = extension ) of the current file:
  486.  
  487. Running TeX is possible for file types defined as TeX documents;
  488. initially this is ".tex" only .
  489.  
  490.                                                *** changed with v3.0 ***
  491. Syntax assist and highlighting should be provided when editing style
  492. files, too.  Initially, only the type ".sty" is recognized.
  493.  
  494. The configuration window provides items for editing the file types,
  495. which are recognized as documents or style files.  The file types must
  496. be entered _without_ the leading dot.
  497.  
  498.  
  499.  
  500.  
  501. ========================================================================
  502.                                 Appendix
  503. ========================================================================
  504.  
  505.  
  506. Using the TeX Front End with VTeX/2                  *** new in v2.5 ***
  507. -----------------------------------
  508. In order to run VTeX from the TeX Front End, you just have to specify
  509. the name of the appropriate batch file as the document format, e.g.:
  510.  
  511. % format: vlatex
  512.  
  513. See section 3 above!  You may also change the default format to
  514. "vlatex".
  515.  
  516. Starting with version 2.5, the TeX Front End will also recognize the
  517. format of VTeX's log files, so that the menu item LOCATE NEXT ERROR
  518. works as expected.
  519.  
  520.  
  521.  
  522. The configuration tool TFCONFIG
  523. -------------------------------
  524. In addition to initializing the TeX Font End, the configuration program 
  525. TFCONFIG may also be used for other purposes.  Here is a summary of the 
  526. TFCONFIG invocation:
  527.  
  528.         TFCONFIG [FILE] [OPTION]
  529.  
  530. Available options are:
  531.  
  532.         /N  list contents of configuration file only
  533.         /U  read settings from configuration file and write them
  534.             to the TeX Front End 
  535.         /V  view current settings of the TeX Front End
  536.         /D  delete all settings from the EPM
  537.  
  538. /U is the default option.  In case no FILE is specified, settings are
  539. read from the configuration file .\tfe.cfg.  A given filename is
  540. ignored, if /V or /D is requested.
  541.  
  542.  
  543.  
  544. Known bugs
  545. ----------
  546. * The Alt-T key will always open the TeX menu, regardless of the setting
  547. of `Menu accelerators'.
  548.   
  549. * The name of a TeX file is required to have an extension.
  550.  
  551. * The master file dependency system recognizes only one \input or 
  552. \include command in a line.
  553.  
  554. * A drive letter in a "% master" statement is not always processed
  555. properly.  (There should, however, be no real need for specifying a
  556. drive letter there.)
  557.  
  558. * The error searching facility may sometime display a wrong source file 
  559. or none at all.
  560.  
  561.  
  562.  
  563. Distribution and support
  564. ------------------------
  565. For the current version of this software see
  566.  
  567.         ftp://dante.ctan.org/tex-archive/systems/os2/epmtfe/
  568.  
  569. or any other CTAN host.
  570.  
  571. In case you encounter any problems upon installing or using the TeX 
  572. Front End, please, contact the author:
  573.  
  574. Walter Schmidt <walter.schmidt@arcormail.de>
  575.  
  576. Please, obtain my email address from the latest version of this
  577. document!
  578.  
  579.  
  580.  
  581. Thanks to ...
  582. -------------
  583. ...  Jon Hacker and Rodney Korte for providing the program EPMTeX and
  584. for the permission to use large parts of their source code.  Without the
  585. model EPMTeX I would never have been able to write the TeX Front End.
  586. Wonkoo Kim suggested and created the configuration menu, and he found 
  587. various bugs.
  588.  
  589.  
  590.  
  591. Finally ...
  592. -----------
  593. ... I would like to apologize for my bad English.  English is not my 
  594. native language.  Suggestions for improving this document and the 
  595. messages displayed by the program are welcome.
  596.  
  597.