home *** CD-ROM | disk | FTP | other *** search
/ High Voltage Shareware / high1.zip / high1 / DIR8 / VMAC.ZIP / VMAC111.DOC < prev   
Text File  |  1993-08-05  |  22KB  |  512 lines
  1.  
  2.  
  3.                                     VMAC.COM
  4.                         (Version 1.11   August 5, 1993)
  5.        Macro Compiler for Eric Meyer's VDE (Versions 1.53-1.65 and 1.70+)
  6.  
  7.                                    Reference
  8.  
  9.     VMAC converts VDE macro files with the extensions .VDF and .VDK into 
  10.     text files with the extensions .VTF and .VTK, and vice versa.
  11.  
  12.  
  13.     Contents:
  14.  
  15.         FEATURES
  16.         USAGE
  17.         OPTIONS
  18.         FORMAT OF TEXT FILE (.VT[FK])
  19.             1. BASIC FORM OF MACRO
  20.             2. MACRO KEYS
  21.             3. LABEL
  22.             4. MODE
  23.             5. EQUAL SIGN
  24.             6. DEFINITION
  25.                    A. Key Names in Definitions
  26.                    B. The Special Character (`)
  27.                    C. Wrapping Definitions
  28.             7. WHITESPACE
  29.             8. COMMENTS
  30.                    A. Line Comments
  31.                    B. Comments Following a Definition
  32.         MESSAGES
  33.         UPGRADING TO VERSION 1.70+
  34.         A NOTE ON WILDCARDS
  35.  
  36.  
  37.     =======================================================================
  38.     *=*=*=*=*=*=*=*=*=*=*=*=*=*=*  FEATURES  =*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
  39.     =======================================================================
  40.  
  41.     * Handles macros for VDE Versions 1.53-1.65 and 1.70+.
  42.     * Allows comments in text files
  43.     * Allows definitions in text files to be broken down and written on 
  44.         several lines so that the logical structure is more apparent and so 
  45.         that long definitions can be viewed in their entirety on one screen
  46.     * Uses understandable function key names like [^F7] and [@F10] instead 
  47.         of perplexing numbers like [27] and [40]
  48.     * Handles multiple filenames on the command line and accepts DOS 
  49.         wildcards
  50.     * Displays the line of a text file in which an error was found and 
  51.         indicates the type of error
  52.     * Shows how much free space remains in a macro file
  53.     * Lists all key names when creating a text file so that you can easily 
  54.         see which keys are free for the addition of new macros, or 
  55.         optionally lists only those keys to which macros have been assigned
  56.  
  57.     =======================================================================
  58.     *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*  USAGE  *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
  59.     =======================================================================
  60.  
  61.                     VMAC  {/U7}  Pathname { Pathname ....}
  62.  
  63.                where Pathname = {Drive:\Dir\}Filename.V[DT][FK]
  64.  
  65.     Options for converting macro files to text files (.VD[FK]-->.VT[FK]):
  66.         (none)  = list ALL key names
  67.             /U  = list only names of keys USED for macros
  68.  
  69.     Option for VDE V1.70+:
  70.             /7  = convert .VTF text files to V1.70+ .VDF macro files
  71.  
  72.     DOS wildcards are OK, but read "A NOTE ON WILDCARDS" near the end of 
  73.     this document before using them.
  74.  
  75.  
  76.     =======================================================================
  77.     *=*=*=*=*=*=*=*=*=**=*=*=*=*=*  OPTIONS  *=*=*=*=*=*=*=*=*=**=*=*=*=*=*
  78.     =======================================================================
  79.  
  80.     /U -- LISTING MACRO KEYS
  81.         When VMAC converts a macro file to a text file and no options are 
  82.     specified, it lists all the key names so that you can easily see which 
  83.     ones are free. If you don't like this feature or don't want to use it 
  84.     in a particular case, specify the /U option and only key names that are 
  85.     actually being used for macros will appear in the text file.
  86.         Regarding the function keys F11, F12 and their shifted brethren of 
  87.     the extended keyboard, if macros exist for any of them, they will be 
  88.     listed. Otherwise, they will not appear in the text file.
  89.  
  90.                      ------------------------------------
  91.  
  92.     /7 -- VERSION 1.70+
  93.         This option is used to convert .VTF function key text files to .VDF 
  94.     macro files that can be loaded by VDE V1.70+. It increases the number 
  95.     of bytes allowed in a macro from 127 to 255, and places the file 
  96.     identifier for V1.70 at the start of the .VDF file.
  97.         If you forget to set the /7 option, there may be no problem. When 
  98.     VMAC encounters either a label or an Autoexec macro, it automatically 
  99.     sets the file identifier to that for V1.70 and increases the bytes 
  100.     allowed. However, if you have any long macros before the first label or 
  101.     an Autoexec macro occurs, you will get an error message.
  102.  
  103.  
  104.     =======================================================================
  105.     *=*=*=*=*=*=*=*=*=*  FORMAT OF TEXT FILE (.VT[FK])  *=*=*=*=*=*=*=*=*=*
  106.     =======================================================================
  107.     NOTE: In the following, V1.53+ means VDE Versions 1.53 - 1.65,
  108.                        and  V1.70+ means VDE Versions 1.70 - (the latest)
  109.  
  110.                      ------------------------------------
  111.  
  112.     1. BASIC FORM OF MACRO
  113.     In a text file, the basic form of a V1.53+ macro or a V1.70+ macro 
  114.     without a label is:
  115.  
  116.         [Key] Mode = Definition                     { ;; Comment}
  117.                   {= Continuation of Definition}    { ;; Comment}
  118.  
  119.     For a V1.70+ macro with a label, it is:
  120.  
  121.         [Key] < Label > Mode = Definition                     { ;; Comment}
  122.                             {= Continuation of Definition}    { ;; Comment}
  123.  
  124.                      ------------------------------------
  125.  
  126.     2. MACRO KEYS
  127.     Key names are always enclosed in brackets, [ ]. VMAC uses the function 
  128.     key names displayed by VINST.COM V1.70+ even for V1.53+ macro files 
  129.     because they are much easier to understand.
  130.     The key names in a text file must be in the order given here.
  131.  
  132.         Character Keys in a .VTK file:
  133.  
  134.                 Numbers           [0]...[9]
  135.                 Letters           [A]...[Z]
  136.  
  137.         Function Keys in a .VTF file:
  138.  
  139.                 Unmodified       [F1]...[F10]
  140.                 <Shift>         [!F1]...[!F10]
  141.                 <Ctrl>          [^F1]...[^F10]
  142.                 <Alt>           [@F1]...[@F10]
  143.                 Extended        [F11]   [F12]
  144.                                 [!F11]  [!F12]
  145.                                 [^F11]  [^F12]
  146.                                 [@F11]  [@F12]
  147.  
  148.                      ------------------------------------
  149.  
  150.     3. LABEL (<xxxxxxx>)
  151.     After the key name a label is optional for V1.70+. Labels are enclosed 
  152.     in angled brackets, < >, and can be at most 7 characters long.
  153.         e.g. [F1] < Help  > N = ^J
  154.  
  155.     If you don't use the full 7 characters, as in <Help>, the remainder 
  156.     will be padded with spaces. If there is nothing or only spaces between 
  157.     the brackets, it's the same as no label at all.
  158.  
  159.                      ------------------------------------
  160.  
  161.     4. MODE
  162.     After the key name or label comes the mode:
  163.         (none)   N (No repeat)   Q (Quiet)   B (Both)    A (Autoexec)
  164.  
  165.     These can be combined as long as no conflict occurs,
  166.          e.g.   NQ    AQ    BA    ANQ,
  167.     but QB and NB are not allowed because B contains Q and N.
  168.  
  169.     The Autoexec mode is available only in VDE V1.70+, and only one 
  170.     function key can be assigned this mode.
  171.  
  172.                      ------------------------------------
  173.  
  174.     5. EQUAL SIGN (=)
  175.     After the mode comes an equal sign. This is used as a signal that a 
  176.     definition follows. If an equal sign is the first non-whitespace 
  177.     character on a line, it means that the definition that follows is a 
  178.     continuation. For example, the following two forms of the definition 
  179.     yield identical results when converted.
  180.  
  181. [!F3]  B = ^Qd^D[Esc]=^M]^S^S[Esc]= 1^D [Esc]1^D^D[Esc]![
  182.  
  183. [!F3]  B = ^Qd^D[Esc]=^M]
  184.          =    ^S^S[Esc]= 1^D` 
  185.          =    [Esc]1^D^D[Esc]![
  186.  
  187.                      ------------------------------------
  188.  
  189.     6. DEFINITION
  190.     A definition has the same general appearance as it does when viewed in 
  191.     VINST.COM:
  192.           ^ indicates <Ctrl>,                    e.g. ^K    ^Q
  193.           @ indicates <Alt>,                     e.g. @P    @L
  194.           [xxx] indicates a key name             e.g. [Up]  [^BkSp]
  195.           other characters represent themselves, e.g. t     Z     :
  196.  
  197.     A. Key Names in Definitions
  198.         Just as for macro keys, key names are enclosed in brackets, [ ]. 
  199.         And they are case insensitive, so [Home] is the same as [home] or 
  200.         [HOME] or whatever.
  201.         The key names recognized are:
  202.  
  203.                Unmodified    <Ctrl>      <Shift>
  204.                ~~~~~~~~~~    ~~~~~~      ~~~~~~~
  205.                [Down]        [^Down]     [!Down]
  206.                [End]         [^End]      [!End]
  207.                [Home]        [^Home]     [!Home]
  208.                [Left]        [^Left]     [!Left]
  209.                [PgDn]        [^PgDn]     [!PgDn]
  210.                [PgUp]        [^PgUp]     [!PgUp]
  211.                [Right]       [^Right]    [!Right]
  212.                [Up]          [^Up]       [!Up]
  213.  
  214.                [Del]         [^BkSp]     [!Tab]
  215.                [Esc]         [^Esc]
  216.                [Ins]         [^Ins]
  217.  
  218.                [+] (Keypad)
  219.                [-] (Keypad)
  220.                [5] (Keypad)
  221.  
  222.         VMAC will recognize ^[ for [Esc], but it always writes [Esc] when 
  223.         creating a text file. [Enter] is indicated by ^M, and [^Enter] by 
  224.         ^J.
  225.         Except for [!Tab], the shifted keys indicate block marking commands 
  226.         executed by pressing the key while holding [Shift] down.
  227.         And notice that, for arrow keys, VMAC uses words as in [Up], [^Up], 
  228.         etc. instead of the symbols [^], [^^], etc. that appear in 
  229.         VINST.COM.
  230.  
  231.     B. The Special Character (`).
  232.         Since the characters ^, @, and sometimes [ have special meanings, 
  233.         there has to be a way to cancel out that special meaning so that 
  234.         these characters can be entered in a definition as themselves. That 
  235.         is the basic function of the special character (`). You place it in 
  236.         front of a character that should be interpreted literally, with no 
  237.         special meaning attached. So, if you want to enter any of the three 
  238.         characters ^, @, or ` as itself in a definition, use the forms:
  239.                 `^     `@     ``
  240.         If you want to enter the string '[Esc]' so that it won't be 
  241.         interpreted as a key name, put a special character in front of the 
  242.         left bracket:
  243.                 `[Esc]
  244.  
  245.         Example: Entering the Epson Printer Initialization Code (Esc @) in 
  246.         a printer setup string.
  247.  
  248.         [@F5] N = ^Kp'^P[Esc]`@^P[Esc]l^B^P[Esc]Q5'
  249.                       ~~~~~~~~~
  250.  
  251.         This use of (`) is a convention borrowed from E. Slawson's VMC.COM 
  252.         (as is the use of the file extensions .VTF and .VTK). But this 
  253.         character has additional importance in VMAC, as explained in the 
  254.         section on whitespace.
  255.  
  256.     C. Wrapping Definitions
  257.         When VMAC creates a text file, it wraps long definitions around to 
  258.         the next line so that you can see the whole thing on one screen. 
  259.         But when it converts a text file to a macro file, it pays no 
  260.         attention to line length, so you can write long definitions on a 
  261.         single line if you want.
  262.  
  263.                      ------------------------------------
  264.  
  265.     7. WHITESPACE
  266.     Whitespace (spaces and tabs) before the start of a definition is 
  267.     ignored, so the following two forms are equivalent.
  268.  
  269.     [L] B = ^Y^X^U
  270.  
  271. [L]B=^Y^X^U
  272.  
  273.     This means that, if a definition or its continuation begins with a 
  274.     space, you have to indicate that fact with the special character (`).
  275.  
  276.     This definition begins with 3 spaces.
  277.     [S] B = `   XYZ
  278.  
  279.     This definition begins with the letter X.
  280.     [S] B =     XYZ
  281.  
  282.     As a visual aid, when VMAC converts a macro file to a text file, it 
  283.     places a special character in front of a space that occurs at the end of 
  284.     a line. The following definitions both end with two spaces, and it is 
  285.     clear which one is easier to understand.
  286.  
  287.     [D] B = ^Og@G2  
  288.     [D] B = ^Og@G2 ` 
  289.  
  290.     For the same reason that you have to put a special character at the 
  291.     start of a line when it begins with a space, you MUST put one in front 
  292.     of a space at the end of a line if you add a comment to the line. And 
  293.     that brings us to the next section.
  294.  
  295.                      ------------------------------------
  296.  
  297.     8. COMMENTS
  298.     There are two kinds of comments: line comments and comments written 
  299.     after a definition.
  300.  
  301.     A. Line Comments
  302.         When converting a text file to a macro file, VMAC pays attention 
  303.         only to lines beginning with either the left bracket ([) of a key 
  304.         name or the equal sign (=) of a continuation. Blank lines and lines 
  305.         beginning with any other character are ignored. So, you can insert 
  306.         blank lines freely to make the text more readable and write 
  307.         comments anywhere as long as they don't begin with either of these 
  308.         two characters.
  309.  
  310.         Example:  The line beginning with "-----" is a comment line.
  311.  
  312.             ----- Transpose Lines Down -----
  313.             [L] B = ^Y^X^U
  314.  
  315.     B. Comments Following a Definition
  316.         Comments after a definition begin with the pattern:
  317.  
  318.             space + semicolon + semicolon  ( ;;)
  319.  
  320.         Spaces between the end of a definition and this pattern are 
  321.         ignored. This is why you have to put a special character in front 
  322.         of a space at the end of a definiton when you use this type of 
  323.         comment. If you actually have to use this pattern in a definition, 
  324.         then put a special character in front of either of the semicolons 
  325.         to break it up, e.g.   space + semicolon + ` + semicolon  ( ;`;).
  326.  
  327.         Example:  The special character (`) at the end of the definition is 
  328.         necessary because of the comment that follows.
  329.  
  330.             [B] B = ^Og@G2`      ;; paraGraph tab,  bullet, space
  331.  
  332.         If you put a comment close to a special character, as in
  333.  
  334.             [B] B = ^Og@G2` ;; paraGraph tab,  bullet, space,
  335.  
  336.         then the space will do double duty as the last character of the 
  337.         macro and as part of the pattern signaling a comment. 
  338.  
  339.  
  340.     =======================================================================
  341.     *=*=*=*=*=*=*=*=*=**=*=*=*=*=*  MESSAGES *=*=*=*=*=*=*=*=*=**=*=*=*=*=*
  342.     =======================================================================
  343.  
  344.     VMAC writes only data that you need to the screen -- no advertising, no 
  345.     addresses or telephone numbers, no implied threats of prosecution for 
  346.     copying the code or documentation -- just essential information. It 
  347.     issues the usual error messages if it can't find a file or can't read it 
  348.     or something like that. In addition, if it finds a problem in a text 
  349.     file, it issues messages like the following that enable you to pinpoint 
  350.     the problem and quickly correct it:
  351.  
  352. <IMET.VTK>
  353. [Z] B = ^Or70^M^Op60^M
  354.     The maximum size of a macro file was exceeded in this line by 6 bytes.
  355.  
  356. <SPQR.VTF>
  357. [^FA] B = ^Kb^Qc^Kk^K#1^M^Qb^Kh
  358.     The macro key name is invalid, nonexistent, or not in the proper order.
  359.  
  360.     If the conversion is successful, it writes:
  361.  
  362. VRGN.VDF created.  506 bytes of free space.
  363.  
  364.  
  365.     =======================================================================
  366.     *=*=*=*=*=*=*=*=*=*=*  UPGRADING TO VERSION 1.70+ *=*=*=*=*=*=*=*=*=*=*
  367.     =======================================================================
  368.  
  369.     For .VDF files, just convert them to .VTF text files with VMAC, add 
  370.     labels or do other editing if desired, and then use the /7 option to 
  371.     convert the text files back into .VDF files.
  372.  
  373.     For .VDK files, rename them to .VDF files and proceed as above.
  374.  
  375.  
  376.     =======================================================================
  377.     *=*=*=*=*=*=*=*=*=*=*=*=* A NOTE ON WILDCARDS *=*=*=*=*=*=*=*=*=*=*=*=*
  378.     =======================================================================
  379.  
  380.     The DOS wildcards (? *) can be used in the filename or extension.
  381.          e.g.     WXYZ.VD?    X*.VTK    *.VDK.
  382.     But be aware of one hazard in using a wildcard for the 'D' or 'T' in the 
  383.     extension. Suppose you want to convert the text files WXYZ.VTF and 
  384.     WXYZ.VTK to macro files and you use WXYZ.* on the command line. The 
  385.     situation progresses like this:
  386.  
  387.     1) Initial situation:
  388.             Directory entries
  389.                 WXYZ.VTF
  390.                 WXYZ.VTK
  391.  
  392.     2) Processing begins and occurs as expected.
  393.             Directory entries
  394.                 WXYZ.VTF   <-- processed by VMAC
  395.                 WXYZ.VTK
  396.                 WXYZ.VDF      <-- created
  397.  
  398.   3) This step is also what you would expect.
  399.             Directory entries
  400.                 WXYZ.VTF
  401.                 WXYZ.VTK   <-- processed by VMAC
  402.                 WXYZ.VDF
  403.                 WXYZ.VDK      <-- created
  404.  
  405.   4) Unexpectedly, DOS feeds the names of the newly created files to the 
  406.     program because it simply walks down the list of directory entries 
  407.     looking for matches. And so the macro files that were just made are 
  408.     converted back into text files, wiping out any comments you may have 
  409.     written.
  410.             Directory entries
  411.                 WXYZ.VTF      <-- OVERWRITTEN!!!
  412.                 WXYZ.VTK
  413.                 WXYZ.VDF   <-- processed by VMAC
  414.                 WXYZ.VDK
  415.  
  416.     5) Processing stops after this step because there are no more files 
  417.     matching the pattern.
  418.             Directory entries
  419.                 WXYZ.VTF
  420.                 WXYZ.VTK      <-- OVERWRITTEN!!!
  421.                 WXYZ.VDF
  422.                 WXYZ.VDK   <-- processed by VMAC
  423.  
  424.     So, you should use WXYZ.VT? to convert both text files at the same
  425.     time.
  426.  
  427.  
  428.     =======================================================================
  429.     *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=* THANKS! *=*=*=*=*=*=*=*=*=*=*=*=*=*=*=*
  430.     =======================================================================
  431.  
  432.     It is impossible for me to express the gratitude I feel toward Eric 
  433.     Meyer for writing VDE, for making it available for all to use, and for 
  434.     being so generous with his time in responding to (sometimes not well 
  435.     thought out) questions, (often silly) suggestions, and (usually 
  436.     unnecessary) complaints.
  437.  
  438.     I would also like to thank Eric Tauck for the wonderful (and free) 
  439.     little program The Wolfware Assembler for which the source code for 
  440.     VMAC was written.
  441.  
  442.  
  443.     ========================================================================
  444.  
  445.                     The program VMAC.COM is absolutely free.
  446.  
  447.     ========================================================================
  448.  
  449.                                    DISCLAIMER
  450.  
  451.     I disclaim responsibility for any bad things that happen as a result of 
  452.     using this program.
  453.  
  454.     ========================================================================
  455.  
  456.                              Richard Cowell
  457.                              S.K. Heights #6
  458.                              Suwa 239, Takatsu-ku
  459.                              Kawasaki, Kanagawa  213
  460.                              JAPAN
  461.  
  462.  
  463.     ========================================================================
  464.                            End of VMAC.COM Reference
  465.     ========================================================================
  466.  
  467.  
  468.          ----------------end-of-author's-documentation---------------
  469.  
  470.                          Software Library Information:
  471.  
  472.                     This disk copy provided as a service of
  473.  
  474.                            Public (software) Library
  475.  
  476.          We are not the authors of this program, nor are we associated
  477.          with the author in any way other than as a distributor of the
  478.          program in accordance with the author's terms of distribution.
  479.  
  480.          Please direct shareware payments and specific questions about
  481.          this program to the author of the program, whose name appears
  482.          elsewhere in  this documentation. If you have trouble getting
  483.          in touch with the author,  we will do whatever we can to help
  484.          you with your questions. All programs have been tested and do
  485.          run.  To report problems,  please use the form that is in the
  486.          file PROBLEM.DOC on many of our disks or in other written for-
  487.          mat with screen printouts, if possible.  PsL cannot debug pro-
  488.          programs over the telephone, though we can answer questions.
  489.  
  490.          Disks in the PsL are updated  monthly,  so if you did not get
  491.          this disk directly from the PsL, you should be aware that the
  492.          files in this set may no longer be the current versions. Also,
  493.          if you got this disk from another vendor and are having prob-
  494.          lems,  be aware that  some files may have become corrupted or
  495.          lost by that vendor. Get a current, working disk from PsL.
  496.  
  497.          For a copy of the latest monthly software library newsletter
  498.          and a list of the 4,000+ disks in the library, call or write
  499.  
  500.                            Public (software) Library
  501.                                P.O.Box 35705 - F
  502.                             Houston, TX 77235-5705
  503.  
  504.                                 1-800-2424-PSL
  505.                              MC/Visa/AmEx/Discover
  506.  
  507.                           Outside of U.S. or in Texas
  508.                           or for general information,
  509.                               Call 1-713-524-6394
  510.  
  511.  
  512.