home *** CD-ROM | disk | FTP | other *** search
/ Mega Top 1 / os2_top1.zip / os2_top1 / APPS / TEKST / EPMTEX20 / DOC / EPMTEX.DOC next >
Encoding:
Text File  |  1994-08-15  |  20.8 KB  |  504 lines
  1.                TeX Macro Enhancements for EPM 5.51a and EPM 6.00c
  2.  
  3.                                   Version 2.0
  4.  
  5.                                  User's Manual
  6.  
  7.                                    Jon Hacker
  8.                                   Rodney Korte
  9.  
  10.                                   August 1994
  11.  
  12. Disclaimer:
  13. ~~~~~~~~~~~
  14.  
  15. See the attached license.txt file that is more or less pilfered from IBM's
  16. license agreement.
  17.  
  18.  
  19. Introduction:
  20. ~~~~~~~~~~~~
  21. The E macro file tex.e, when compiled with the IBM enhanced Editor
  22. translator ETPM.EXE, will add a TeX pull down menu to the EPM menu bar.
  23.  
  24. Menu items in the TeX pull down menu allow the user to TeX (with any format,
  25. e.g. LATeX), jump to errors in the TeX source, preview (portrait and
  26. landscape), and print (portrait and landscape) the TeX file currently active
  27. in EPM.  Two custom 'user' modes may also be defined for special needs
  28. unique to the user.
  29.  
  30. TeX can be forced to use one of 4 formats (all user-definable) when TeXing
  31. source code.  However, a general 'automatic' mechanism is provided so that
  32. *any* format can be specified in the first line of the TeX file.  This is
  33. the same method used in texit.cmd by Eberhard Mattes.
  34.  
  35. For large projects, a "Master" file scheme is supported, using a method
  36. similar to the automatic format selection method.  This allows the user to
  37. break a large document into many smaller, more manageable ones with fewer
  38. hassles.
  39.  
  40. Paper orientation for viewing and printing also can be defined in the
  41. first line of the TeX file, or chosen through the TeX menu.
  42.  
  43. TeX syntax assist and TeX accelerator keys can be enabled for files with
  44. extensions .tex, .sty, .aux, or .log, plus any other extensions defined by
  45. TEX_USER_FILE_TYPES in MYCNF.E.
  46.  
  47. Sample TeX files are included in the EXAMPLES directory to demonstrate
  48. the EPMTeX package.  See the file EXAMPLES\T-MAIN.TEX to get started.
  49.  
  50.  
  51. The Master File Concept
  52. ~~~~~~~~~~~~~~~~~~~~~~~
  53. It is useful to break a large document into smaller, more manageable parts.
  54. The idea is to create a small file, which contains initialization commands,
  55. special definitions, etc., and then includes other files which have the
  56. actual text of the document.  This small file is the "Master" file.  For
  57. example we might have the following Master file, NOISE.TEX:
  58.  
  59.         % Format: TeXsis         % Use the TeXsis format
  60.         \paper                   % Set page layout
  61.         \TrueDoubleSpacing       % Set doublespacing
  62.         \draft                   % Put into draft mode
  63.         \input NOISE-REFS        % References
  64.         \input NOISE-INTRO       % Introduction
  65.         \input NOISE-SEC1        % Section 1
  66.         \input NOISE-SEC2        % Section 2
  67.         \input NOISE-SEC3        % Section 3
  68.         \input NOISE-CONC        % Conclusion
  69.         \ListReferences          % List all References
  70.         \end
  71.  
  72. The first line will tell EPMTeX (and Eberhard Mattes' texit.cmd) that
  73. the TeXsis format should be used when TeXing this file.  Lines 2-4 are
  74. TeXsis commands that set the page layout and other things that apply to
  75. the entire document.  The references, as well as each of the 5 sections
  76. of the paper, are in a separate files which are read in one after another.
  77. The second-to-last line then prints out the references and finally the
  78. document ends.
  79.  
  80. This scheme is useful since not only is the document well organized, now
  81. sections of the paper can be worked on individually by simply commenting
  82. out those sections which need not be compiled.  When everything is working,
  83. just uncomment all the sections and recompile.
  84.  
  85.  
  86. Installation:
  87. ~~~~~~~~~~~~
  88. For installation instructions see the file install.doc included with
  89. this package.  If you are upgrading from v1.3, you can probably get up
  90. to speed faster by reading section 2 of the install manual.  This is a
  91. concise description of what you need to do to get running and assumes
  92. you already understand the basics of compiling epm E files, and the
  93. EPMTeX package.
  94.  
  95.  
  96. Using the EPM Pull Down Menu for TeX:
  97. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  98.    This is a description of the menu items that appear on the TeX sub-menu
  99.    after installing EPMTeX v2.0beta.  The TeX menu will be greyed out for
  100.    non-Tex files.  (TeX files are defined as having extensions .tex, .log,
  101.    .aux and .sty.  You can also specify extensions of your own choice by
  102.    defining the variable TEX_USER_FILE_TYPES in your MYCNF.E file.)
  103.  
  104.  **A double asterisk following the menu choice below signifies that
  105.    determination of the "Master" file is the first thing that is done after
  106.    this choice is made.  If a "Master" file specification is found, EPM
  107.    changes the default directory to that directory (so that log files, etc.,
  108.    end up in that directory) and executes the command associated with that
  109.    menu item on the Master file, not the current file.  The Master file can
  110.    be specified in any of the following ways (the master file is MYMAIN.TEX):
  111.         % Master: mymain
  112.         % master: mymain
  113.         % Master  mymain
  114.         % master  mymain
  115.    Any number of spaces can be used between any of the elements in the line.
  116.    All Master and "Slave" (those input from the master) files are assumed to
  117.    be in the same directory.  However, they can be placed in different
  118.    directories *if* they are always referenced with a fully qualified
  119.    pathname (no relative path specifications). Forward or back slashes can be
  120.    used in the Master specification above, but remember to use forward slashes
  121.    in \input lines since TeX will interpret backslashes as command sequences.
  122.  
  123.    If a master file is specified but does not actually exist, EPMTeX will
  124.    ask if you want to stop processing or continue as if the Master
  125.    directive was not issued.  This has the (nifty) side-effect that you
  126.    can do something like
  127.         % Format: lplain  Master : mymain  Orientation:Landscape
  128.    for the first line of a file.  If you want to TeX only the current file,
  129.    simply modify 'mymain' to something like 'mymain1' and then TeX the
  130.    current file.  Note that you would then have a .log and .dvi (and maybe
  131.    other) files lying around that you won't want later!  Note that this
  132.    question will pop up for any of the operations below that check for
  133.    a master file name.
  134.  
  135.    Two other "First line directives" are described below: "Format" and
  136.    "Orientation."  Note that they can appear in any order on the first
  137.    line of the file. To reiterate, the "Master" directive is processed
  138.    first.  If a master file is defined and exists, the Format and
  139.    Orientation directives in the *current* file are ignored.  But if
  140.    a master file is defined but does *not* exist, they *will* be used.
  141.    (Hang on, it does make sense!)
  142.  
  143.  
  144. >TeX Document **
  145.  
  146.    Calls the version of TeX specified by the variable TEX_EXEC in TEXENV.E
  147.    with the format to be used and the name of the current (or Master) file
  148.    appended. Note that the appended filename is specified with UNIX type
  149.    directory delimiters (ie.  '/') so that TeX will not barf.
  150.  
  151.    The format to be used is given by the "Format" menu item.  If "Automatic"
  152.    is not chosen (one of the other ones is) the format defined in TEXENV.E
  153.    for that menu entry or the format chosen in the Format menu will be used.
  154.    If "Automatic" is chosen, an attempt is made to determine the format from
  155.    the first line of the current (or Master) file.  The format can be
  156.    specified in any of the following ways (lplain is the format used here):
  157.  
  158.         % Format: lplain
  159.         % format: lplain
  160.         % Format  lplain
  161.         % format  lplain
  162.         %Format:lplain
  163.         %format : lplain
  164.         % format :lplain
  165.           ... etc ...
  166.  
  167.    Any number of spaces can be used between any of the elements in the line.
  168.    If the format is not specified but "Automatic" is chosen, EPMTeX will
  169.    issue a warning and continue with the format defined by TEX_FORMAT_PLAIN.
  170.    Note that the format specification only need be placed in the Master
  171.    file, not the slave files.
  172.  
  173.    Note that the format you specify does have to correspond to any format
  174.    defined in the Formats menu (described below).  If you specify a format
  175.    that doesn't exist, EPMTeX won't care, but TeX will- you'll get a
  176.    'Sorry, I can't find that format; will try PLAIN' error.
  177.  
  178.    If the AutoSave option is checked in the TeX pulldown menu, the current
  179.    file will first be saved to disk if the version in EPM memory has been
  180.    modified.  If a Master file is defined, EPM loads the Master file and
  181.    scans it for "\input file_name" commands, and checks to see if file_name
  182.    is in the ring.  If it is, and has been modified, EPM will save the file.
  183.    If AutoSave is not checked, EPM will ask you if you wish to save the file
  184.    before TeXing.
  185.  
  186.    This action also resets the Error Locating routine to the beginning of
  187.    the LOG file.
  188.  
  189. >Locate Next Error **
  190.  
  191.    If the LOG file for the current (or Master) file exists, this action will
  192.    load the log file, determine the TeX source file in which the first error
  193.    resides, load that file, position the cursor at the error, and print the
  194.    error message on the message line.
  195.  
  196.    Subsequent selection of this action will cause a search for the next
  197.    error until all errors have been located.
  198.  
  199.    Selecting either the "View LOG File" or "TeX Document" menu options
  200.    resets the search to the beginning of the LOG file.
  201.  
  202.    Note that if you are using a Master file and include a 'slave' file that
  203.    does not have the Master specification in the first line, and EPMTeX
  204.    locates an error in this file, you will have to switch to a file in the
  205.    ring that does have the master file defined to locate subsequent errors.
  206.    This is due to the fact that the error routine will look for a LOG file
  207.    associated with the slave file, not the master, to locate the next error.
  208.    In most cases, it will not exist, so the menu item will be greyed out.
  209.    BE AWARE: if it *does* exist, you may have some trouble since the error
  210.    routine will be looking in the wrong LOG file for the next error!
  211.  
  212. > View LOG File **
  213.  
  214.    If the LOG file exists, this command will load the associated LOG file for
  215.    the current (or Master) TeX file into the EPM file ring.  If there is a
  216.    LOG file currently in the ring, it is removed before the new LOG file is
  217.    loaded.
  218.  
  219.    This action also resets the Error Locating routine to the beginning of
  220.    the LOG file.
  221.  
  222. >Preview Document **
  223.  
  224.    Calls the TeX previewer specified by the variable TEX_VIEW_EXEC (or
  225.    TEX_VIEWLA_EXEC if landscape orientations is selected) with the name of
  226.    the associated DVI file for the current (or Master) file loaded in EPM
  227.    appended.
  228.  
  229.    The TeX previewer specified by the variable TEX_VIEW_EXEC should be the
  230.    previewer used for portrait orientation.  The TeX previewer specified by
  231.    the variable TEX_VIEWLA_EXEC should be the previewer used for landscape
  232.    orientation.
  233.  
  234.    If the Auto LOG Delete option is checked in the TeX pulldown menu, the
  235.    associated LOG file for the current (or Master) file will be
  236.    automatically deleted if it exists.
  237.  
  238. >Print Document **
  239.  
  240.    Calls the TeX dvi printer driver specified by the variable TEX_PRINT_EXEC
  241.    (or TEX_PRINTLA_EXEC if landscape orientation is selected) with the name
  242.    of the associated DVI file for the current (or Master) file loaded in EPM
  243.    appended.
  244.  
  245.    The TeX printer driver specified by the variable TEX_PRINT_EXEC should be
  246.    the printer driver used for portrait orientation.  The TeX printer driver
  247.    specified by the variable TEX_PRINTLA_EXEC should be the printer driver
  248.    used for landscape orientation.
  249.  
  250.    If the Auto LOG Delete option is checked in the TeX pulldown menu, the
  251.    associated LOG file for the current (or Master) file will be automatically
  252.    deleted if it exists.
  253.  
  254. >  User Defined Command #1 **
  255.  
  256.    The command defined as TEX_USER1_EXEC (or TEX_USER1LA_EXEC if landscape
  257.    orientation is chosen) in TEXENV.E will be executed.
  258.  
  259. >  User Defined Command #2 **
  260.  
  261.    The command defined as TEX_USER2_EXEC (or TEX_USER2LA_EXEC if landscape
  262.    orientation is chosen) in TEXENV.E will be executed.
  263.  
  264. > Delete LOG File **
  265.  
  266.    If file exists, this command will delete the associated LOG file for the
  267.    current (or Master) file loaded in EPM.  It also removes this LOG file
  268.    from the ring if it exists.
  269.  
  270. > Delete DVI File **
  271.  
  272.    If file exists, this command will delete the associated DVI file for the
  273.    current (or Master) file loaded in EPM.
  274.  
  275. > Format
  276.  
  277.    The chosen format will have a checkmark beside it.  If "Automatic" is
  278.    chosen, EPMTeX will attempt to determine the format to be used from the
  279.    first line of the current (or Master) file.  If no format is specified
  280.    on the first line, the format defined by TEX_FORMAT_PLAIN will be used.
  281.    If one of the other formats is selected, EPMTeX will explicitly specify
  282.    the format associated with this selection in TEXENV.E on the tex command
  283.    line.
  284.  
  285.    There is no specific "German" mode in this release.  Rather, German TeX
  286.    support is included as part of this more general format selection
  287.    method.  The German versions of the plain and LATeX formats can be
  288.    defined in TEXENV.E, and can be chosen from this menu.
  289.  
  290.    If the constant TEX_FORMAT_TO_USE is defined (in MYCNF.E) to be
  291.    something other than one of the four formats defined in TEXENV.E,
  292.    none of the formats shown in the Format menu will be checked.
  293.  
  294. > Orientation
  295.  
  296.    The chosen paper orientation will have a checkmark beside it.  If
  297.    "Automatic" is chosen, EPMTeX will attempt to determine the orientation
  298.    to be used from the first line of the current (or Master) file.  If no
  299.    orientation is specified on the first line, Portrait will be used.  If
  300.    "Portrait" or "Landscape" is chosen, the orientation specified on the
  301.    first line of the file will be overridden.
  302.  
  303.    If the orientation is determined to be landscape, the landscape versions
  304.    of the TeX previewer and printer driver (and the two user-defined
  305.    commands) are used (specified by TEX_VIEWLA_EXEC and TEX_PRINTLA_EXEC
  306.    respectively).  Otherwise, the portrait versions (specified by
  307.    TEX_VIEW_EXEC and TEX_PRINT_EXEC respectively) are used.  The same
  308.    holds true for the two user-defined commands.
  309.  
  310.    The orientation is specified in a manner similar to that of the
  311.    Format specification above, but there are only two possible orientations:
  312.    "Landscape" and "Portrait".  Example specifications:
  313.  
  314.         % Format: lplain  Orientation:Landscape
  315.         % Format: TeXsis  Orientation:Portrait
  316.         % Orientation:Landscape  Format:MyFormat
  317.  
  318.  
  319. > Auto LOG Delete
  320.  
  321.    If enabled (checkmark beside menu entry) the associated LOG file for the
  322.    current (or Master) file will be automatically deleted if it exists when
  323.    a preview or print command is executed.
  324.  
  325. > Auto Save
  326.  
  327.    If enabled (checkmark beside menu entry) the current file will first be
  328.    saved to disk if the version in EPM memory has been modified before the
  329.    document is TeX'd.  Otherwise, the user will be prompted to save the file.
  330.  
  331. > Syntax Expansion
  332.  
  333.    NOTE: This option is not available if TeX syntax assist was not included
  334.    at compile time (default is to include it.  Set TEX_SYNTAX_ASSIST = 0 to
  335.    not include it.).
  336.  
  337.    If enabled (checkmark beside menu entry) then the built-in TeX syntax
  338.    expansions will be enabled.  This is equivalent to typing 'expand on' at
  339.    the EPM command line.  The start-up mode is defined by the configuration
  340.    constant MY_EXPAND_ON described in the EPM documentation.
  341.  
  342. > Debug mode
  343.  
  344.    If enabled (checkmark beside menu entry) the contents of the command
  345.    line sent to the OS/2 'start' command will be displayed on the EPM message
  346.    line.  This can be useful when debugging the various TeX commands during the
  347.    installation of the EPMTeX enhancements.  It is normally turned off.  Note
  348.    that a list of recent messages can be retrieved in EPM under
  349.    options->messages.
  350.  
  351. > About
  352.  
  353.    Self-explanatory?
  354.  
  355.  
  356. Using the TeX Syntax Assist for EPM:
  357. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  358.  
  359. The TeX syntax assist provided with EPMTeX was developed by Jo Koenen.
  360. If you have suggestions, or better yet source code, that will expand
  361. the functionality of this section we would love to hear from you.
  362.  
  363. This is a brief description of the syntax assist and accelerator keys
  364. added if TEX_SYNTAX_ASSIST is included at compile time.
  365.  
  366.  
  367. > Syntax Expansion:
  368.  
  369. If TEX_SYNTAX_ASSIST = 1 is specified in your MYCNF.E file, then the
  370. following syntax expansions will be defined.
  371.  
  372. Loading a file with the extension .tex, .sty, .aux, or .log into EPM enables the
  373. following enhancements: (the vertical bar | denotes the cursor position)
  374.  
  375.  
  376. 1.  \be (including the blank after \be !!)  will be expanded to
  377.     \begin{|}
  378.  
  379.     now you can enter a TeX-word like itemize
  380.  
  381.     \begin{itemize}
  382.  
  383.     press enter and you get
  384.  
  385.     \begin{itemize}
  386.     |
  387.     \end{itemize}
  388.  
  389. 2.  \it  (including the blank) will be expanded to
  390.     \item |
  391.  
  392. 3.  \ci  (including the blank) will be expanded to
  393.     \cite{|}
  394.     
  395. That's all I (Jo) have done so far, but it is all source code, therefore
  396. it's expandable. Every suggestion is welcome.
  397.  
  398. >Accelerator Keys:
  399.  
  400. If TEX_WANT_ACCELERATOR_KEYS = 1 is specified in your MYCNF.E file and syntax
  401. expansion is enabled, then the following TeX accelerator keys will be defined.
  402.  
  403. Key assignments (the vertical bar | marks the cursor position):
  404.  
  405.     alt-a:=eqnarray|
  406.     alt-b:=\begin{|}
  407.     alt-c:=\cite{|}
  408.     alt-d:=description|
  409.     alt-e:=equation|
  410.     alt-f:=\frac{|}{}
  411.     alt-h:=\hspace*{|}
  412.     alt-i:=\item|
  413.     alt-j:=itemize|
  414.     alt-k:=tabular|
  415.     alt-l:=\label{|}
  416.     alt-m:=\mbox{|}
  417.     alt-n:=enumerate|
  418.     alt-q:=equation|
  419.     alt-r:=\ref{|}
  420.     alt-s:=\sqrt{|}
  421.     alt-v:=\vspace*{|}
  422.     alt-w:=verbatim|
  423.      {    :={|}
  424.      $    :=$|$
  425.  
  426.  
  427. Configuration Constants:
  428. ~~~~~~~~~~~~~~~~~~~~~~~
  429.  
  430. The following configuration constants may be included in your MYCNF.E file to
  431. control syntax expansion support and define the start-up behaviour of the
  432. 'Format', 'Landscape mode', 'Auto LOG delete', 'Auto Save', and 'Debug mode'
  433. options.
  434.  
  435.  TEX_SYNTAX_ASSIST
  436.    Set to 1 to include TeX Syntax assist in EPM.  Set to 0 to not include
  437.    this option.  Default is (1), option on.
  438.  
  439.  TEX_MENU_ALWAYS_ON
  440.    Set to 1 to always have access to the TeX submenu, even if a non-TeX file is
  441.    loaded.  Set to 0 to grey out the TeX menu when non-TeX files are loaded.
  442.    Default is (0), greyed menus enabled.
  443.  
  444.  TEX_WANT_ACCELERATOR_KEYS
  445.    Set to 1 to include TeX keyboard accelerator key definitions in EPM.  Set to
  446.    0 to leave the keyboard alone.  Default is (0), option off.  Requires
  447.    TEX_SYNTAX_ASSIST = 1 to be set to have an effect.
  448.  
  449.  TEX_MARGINS
  450.    Set margins to be effective for TeX files. Default is ('1 70 1'). Requires
  451.    TEX_SYNTAX_ASSIST = 1 to be set to have an effect.
  452.  
  453.  TEX_TABS
  454.    Set tabs to be effective for TeX files. Default is (8). Requires
  455.    TEX_SYNTAX_ASSIST = 1 to be set to have an effect.
  456.  
  457.  TEX_ORIENTATION
  458.    Sets the paper orientation to use at start-up.  There are only three
  459.    possible values:
  460.       TEX_ORIENTATION = 'Auto'
  461.       TEX_ORIENTATION = 'Portrait'
  462.       TEX_ORIENTATION = 'Landscape'
  463.  
  464.  TEX_AUTO_DELETE_LOG
  465.    Set to 0 to turn EPMTeX log file auto-delete option off at start-up. Set to 1
  466.    to turn option on at start-up.  Default is (1), option on.
  467.  
  468.   TEX_AUTO_SAVE_DOC
  469.    Set to 0 to turn EPMTeX smart save before TeX option off at start-up. Set to
  470.    1 to turn option on at start-up.  Default is (1), option on.
  471.  
  472.   TEX_DEBUG_MODE
  473.    Set to 0 to turn EPMTeX debug mode off at start-up.  Set to 1 to turn option
  474.    on at start-up.  Default is (0), option off.
  475.  
  476.   TEX_QUICK_KEYS
  477.    Set to 1 to define Sh+F11 to execute the 'TeX Document' menu item and
  478.    Sh+F12 to execute the 'Locate Next Error' menu item. Set to 0 to disable
  479.    this feature.  Default is (1), keys defined.
  480.  
  481.   TEX_FORMAT_TO_USE
  482.    Sets the format to use at start-up.  This would generally be one of the
  483.    formats defined in TEXENV.E ('plain', 'lplain', or one of the two
  484.    user-defined formats), plus the 'auto' format for automatic selection.
  485.    Default is ('auto').
  486.  
  487.    Examples: TEX_FORMAT_TO_USE = 'auto'
  488.              TEX_FORMAT_TO_USE = 'lplain'
  489.  
  490.    Note that the format you specify does have to correspond to any of the
  491.    defined formats.  If you specify a format that isn't defined in TEXENV.E,
  492.    no problem.  If you specify a format that just doesn't exist, EPMTeX
  493.    won't care, but TeX will- you'll get a
  494.         'Sorry, I can't find that format; will try PLAIN' error.
  495.  
  496.   TEX_USER_FILE_TYPES
  497.    Sets file types other than .tex, .sty, .aux, and .log to trigger TeX support.
  498.    The file types do not need to be separated with spaces, although this can be
  499.    done for ease of reading.  Default is ('').
  500.    Examples: TEX_USER_FILE_TYPES = 'FGL TBL REF CNT TOC'
  501.              TEX_USER_FILE_TYPES = 'FGLtbLREFcnttoc'
  502.  
  503.  
  504.