Liren Large Software Subsidy 18

home *** CD-ROM | disk | FTP | other *** search

/ Liren Large Software Subsidy 18 / 18.iso / tools / qmac.doc < prev next >

Wrap

Text File | 1990-02-25 | 28.3 KB | 787 lines

QMac -- QEdit Macro Program A translator utility to convert QEdit binary macro files to and from a more easily used text format. Revision: 2.1 Date: February 27th, 1990 QEdit and QMac are Copyright (C) 1985-1990 by SemWare. All Rights Reserved. DESCRIPTION ----------- QMac is a translator of QEdit macro files. It translates QEdit macros from the binary file in which QEdit saves macros to a text file which allows easy macro editing, and translates such text files back into a QEdit binary file. This allows you to "record" a macro using QEdit; fine-tune it by editing the text representation of the macro; and then translate the edited version and reload it into QEdit for replay. QMac allows appending to or overwriting existing files, making it easy to add new macros to existing files. QMac's text file format allows comments, permitting documentation of the macros within their "source file". TABLE OF CONTENTS ----------------- Description ................................................ 1 Table Of Contents .......................................... 1 What's New? ................................................ 2 License .................................................... 2 Quick Start ................................................ 2 Running QMac ............................................... 4 Text File Format on Input .................................. 6 Text File Format on Output ................................. 9 Error Messages ............................................. 11 Acknowledgements & Contacts................................. 15 Revision History ........................................... 15 QMac 2.1 Documentation Page 2 WHAT'S NEW? ----------- o You now must include a pound sign "#" in front of an ASCII code. This is to allow for future extensions of the macro language. o Jump, JTrue and JFalse are now supported in QMac macros. There may be up to 32 labels in each macro, each of which can be the target of one or more jump instructions. Only the first 32 characters of a label are significant. o All other new commands in QEdit 2.1, QEdit TSR 1.1, and QEdit for OS/2 1.5 are now supported. This includes CenterLine, FillBlock, RepeatCmd, SetPrintBotMargin, SetPrintTopMargin, ToggleSwap, GrabScreen, GoBack and Purge. LICENSE ------- QMAC is FREE to licensed users of QEdit. You may copy QMAC for purposes of evaluating it, and distribute QMAC to others for purposes of evaluating it for their use. If you continue to use QMAC after evaluating it, you must register your copy of QEdit. See your QEdit documentation for registration information. If you distribute QMAC to others, you must distribute it AS-IS, with no files altered, added, or removed from the package. You may not distribute QMAC in connection with any other product or service, or for any consideration or 'disk fee'. Operators of electronic bulletin board systems (Sysops) are encouraged to post QMAC for downloading by their users, as long as the above conditions are met. Those who have permission from SemWare to distribute or sell QEdit itself are exempt from these restrictions. QUICK START ----------- Here is quick run-through of what you can do with QMac, including recording a macro, saving it to disk, and converting it with QMac. The keystrokes mentioned below assume you are using the default QCONFIG.DAT supplied with QEdit; if you have re- installed your keyboard using QCONFIG, please modify as needed. QMac 2.1 Documentation Page 3 Recording the macro: (1) From inside QEdit, select MacroRecord. (Either hit <Ctrl M> or select "Macro record" from the "Macro" menu in the pull-down menu system, by pressing <Escape><M><M>). (2) At the prompt that says "Assign to what key:" press a key to redefine. We will use <Ctrl F10> (hold down the Ctrl key and press the F10 key). (3) Press Find <Ctrl QF>, type "the" and press Return, and type "IW" and press Return again. (This is just an example of what you can do, you could of course record any legal series of QEdit keystrokes here.) (4) Select MacroRecord again to end the macro, as in step (1) above. (5) Now, you can press <Ctrl F10> to search for the word "the" in your text in just one step. Saving the macro to disk: (6) Let's write this macro to disk in a file that QMac can use. Select MacroWrite from the pull down menus, by pressing <Escape> then <M><W>. (7) Give it a filename of "FIND.MAC", and press Return to save this macro on disk. Converting the macro to text: (8) Press Dos <Alt F9> to send a command to MS-DOS. Type: QMAC FIND.MAC FIND.TXT /A- /T to convert FIND.MAC to a text form in the file FIND.TXT. Press Return. (The /T selects text output). (9) Press EditFile <Alt E> to load this file into QEdit. Type "FIND.TXT" to load the text file you just created with QMac. Press Return. You should see something like this on the screen: * * Converted by QMAC from: C:\FIND.MAC * ^f10 MacroBegin Find "the" Return "IW" Return QMac 2.1 Documentation Page 4 Which is, of course, a text representation of the keystrokes you just recorded. (10) You can now edit your macro if need be. Let's change the word "the" to "and", and save the file back to disk by pressing File <Ctrl KX>. Converting the macro from text back to binary: (11) Press Dos <Alt F9> to send a another command to MS- DOS. This time, type: QMAC FIND.MAC FIND.TXT /A- /B to convert FIND.TXT back to its BINARY form, FIND.MAC. (NOTE that we use /B to tell QMac to make the binary file from the text file we just edited). Press Return. Reloading the edited macro into QEdit: (12) We can reload the modified macro file into QEdit so we can use it. Select MacroRead from the pull down menus, by pressing <Escape> then <M><R>. (13) Specify the same filename as before, "FIND.MAC" to reload the same macro file we've been using. Press Return. (14) Now when you press Ctrl-F10, QEdit will search for the word "and" instead of "the". As you can see, you can use QMac to convert macro files in both directions: from a human-readable text form to the binary form that QEdit uses, and vice versa. RUNNING QMAC ------------ To run QMac, at the DOS prompt type: QMAC ? and press Enter. You will see a summary of QMAC's operation that looks similar to the following: QMac 2.1 Documentation Page 5 ---------------------------------------------------------------- QMAC: QEdit Macro Program II 2.xx dd-mmm-yyyy Copyright (C) 1989, SemWare. All Rights Reserved. QMAC ? for help. QMAC macfile txtfile [ /B | /T ] /A /C /U /M /Q /Ixx /Wyy /Ezz macfile QEdit binary macro file to process txtfile File containing text version of macros /B Binary output: Create macfile from textfile /T Text output: Create textfile from macfile /A Append mode: Append output to existing output file /C+ Continue macros with "&"; /C-: Don't use "&" (default) /U+ Underscores in names; /U-: Don't use underscores (default) /M+ Mixed case names in text output (default); /M-: Use all lower case /Q+ Quote strings with double quote (default); /Q-: Use single quotes /Ixx Indent output text to column xx. (Default=9) /Wyy Wrap output text at column yy. (Default=80) /Ezz Errors to tolerate before quitting. (Default=20) ---------------------------------------------------------------- All of the command line switches are optional, and are only necessary to control QMac's operation in special ways. Do not type the [] characters. The "macfile" parameter is the name (including directory, if needed) of a QEdit binary macro file, such as created by using MacroWrite from inside QEdit. The "txtfile" parameter is the name of a text file that contains a human-readable representation of the same macros. QMac will create whichever of the two files that did not exist already: If the text macros already exist, it will convert them to binary. Or if the binary macros already exist, it will convert them to text. However, if both files exist, you must supply one of the optional switches to determine the direction. The switch /B tells QMac to create a Binary file, while /T tells it to create a text file. If the output file already exists, you must also supply a /A+ or /A- switch to tell QMac whether to "append" to the existing file. With /A+ it will append, /A- tells QMac to overwrite the existing file. All of the other parameters besides /B, /T and /A, are completely optional, and all but /E only affect QMac's operation when it is converting from binary to text format. See later sections for advice on using the other command line switches. QMac 2.1 Documentation Page 6 QMac will prompt for any required parameters which are not supplied at the DOS prompt. This includes the file names, so you can just type: QMAC by itself, and let the program prompt you for information, if you would rather not learn the various parameters. Hitting RETURN all by itself at any QMac prompt will halt QMac. QMac 2.x will also accept the "old style" command line syntax used in previous versions of QMac: QMAC macfile textfile om am Where: om == output mode. Either: T(ext) or B(inary) am == append mode. Either: Y(es) or N(o) This syntax corresponds exactly to the order in which QMac will prompt you for information if you don't supply it. The advantage to using the new command line switches over the old syntax is that the command line switches may be entered in any order on the command line. If a switch appears more than once, or if conflicting switches are specified, the rightmost switch takes precendence. You can mix the old syntax with the new. For instance, if you enter just QMAC /A- at the command line, QMAC will prompt for input, but will not ask about the append mode. TEXT FILE FORMAT ON INPUT ------------------------- The text format which QMac uses for macros is similar to that used within your QCONFIG.DAT file for QEdit: key [ MacroBegin ] [ Command... ] [ & ] [ "string" ] [ xxx ] [ * comment ] .... The "key" name must start in column 1 of a line, and must be a single key (no two-keys allowed). It can either be the name of a key that QEdit understands (such as ^pgup for <Ctrl PgUp>); or the numeric scan code for a key. QMac 2.1 Documentation Page 7 By using the numeric scan code, you can assign macros to special keys that do not exist on your keyboard, but which are generated by a keyboard enhancer program. You can also accomodate non- standard keyboards on some clone PC's that have unusual keys. A macro can optionally begin with the command "MacroBegin", but this is not required in this version of QMac. Following that, the macro can contain any number of commands which QEdit understands. See your QEdit manual for details, but these are commands like "CursorRight", "EditFile", etc. For instance a macro to make the cursor jump to the very first character of the current file would be: @f2 MacroBegin BegFile BegLine If a macro contains only the command "UnknownCommand", then that key will have no action at all when in QEdit. (You might use this to "disable" certain keys in QEdit at certain times. In order to re-enable the keys, you would have to load another macro file with those keys defined, or re-start QEdit). Mixed interchangeably with commands, macros can contain quoted strings of text. These will be "typed" when you execute the macro, just as if you had typed them. Quoted strings can be surrounded by either single or double quote characters. If you need to embed a quote mark in a string, either use the other quote mark to surround the string, or double up the quote mark in the string: 'This is a double quote: " within a string' or "This is a double quote: "" within a string" would enter the following string in the macro: This is a double quote: " within a string Quoted strings can be used to enter text in the file you are editing, or to answer prompts or menus presented by QEdit. QMac 2.1 Documentation Page 8 For other ASCII characters that are difficult to enter, you can include the decimal code directly in the macro. For instance, to include a literal form feed code in a macro, you could enter: "This is a form feed: " #12 and the 12 would be translated to an ASCII 12, or form feed, in the macro. Do not put quotes around an ASCII code entered this way. You can enter any ASCII code from 0 to 255 this way. Be sure to include the pound sign. Anywhere an asterisk ("*") appears on a line, outside of a quoted string, the rest of the line is treated as a "comment" and is ignored by QMac. You can use this to include notes to yourself about how your macros work, or what they are supposed to do. Comments are not included in the binary macro file that QEdit loads, so there is no penalty for including them in your text macro files. A macro can continue onto more than one line, simply indent the second and subsequent lines of the macro one or more spaces. The macro continues until QMac runs out of text or encounters another key at the beginning of a subsequent line. If you include an ampersand ("&") as the very last character on a line, the next line will be included in the macro, even if it is not indented. If you omit ampersands from your multi-line macros, you can more easily reformat them using QEdit. Simply leave a blank line below each macro, and use the WrapPara <Alt B> command in QEdit to re-wrap macros to make them readable. Remember, though, only the key name should appear in column 1, all other lines should be indented one or more spaces. Please note that quoted strings containing spaces, or comments, may be wrapped incorrectly by WrapPara, so be careful. QMac ignores any blank lines or lines that start with a comment ("*") mark, so you can freely intermix those within or between your macros as needed. Lines in your text macro files can be up to 512 characters long. A text macro file may contain an arbitrary number of key definitions. QMac does not check the number or size of macros when creating binary macro files, because the limits on size and number may change from version to version of QEdit. However, it does make a rudimentary check on total size to be sure that the current versions of QEdit will be able to load the macro file. QMac 2.1 Documentation Page 9 You may include any number of blank or tab characters between commands in a macro, and capitalization is not important on input. Also, QMac ignores the underscore ("_") character when used inside command names. So, any of the following are equivalent: ^f2 macro_begin beg_line beg_file un_mark_block ^f2 MaCrO_BeGiN BeG_LiNe BeG_FiLe Un_MaRk_Block ^f2 MACROBEGIN BEGLINE BEGFILE UNMARKBLOCK You can use whichever form pleases you. Note, however, that "_" may not be used inside key names, only inside command names. Underscores can be used inside label names for use with the jump commands, and they will be considered a significant part of the name. So the following labels: My_First_Label: MyFirstLabel: are different labels. Labels are not case sensitive. Place a label before the command to which you wish to jump. A label is distinguished by a trailing colon ":" which is mandatory. TEXT FILE FORMAT ON OUTPUT -------------------------- When creating a text file from a binary macro file, QMac writes macros in the same format as described above. Literal ASCII characters whose decimal codes are between 0 and 31 inclusive (the "control codes") are written to the text macro in decimal form, preceeded by "#". All other quoted characters are written as-is. When interpreting macros containing jump commands, the original names of the labels for the jumps are no longer available. So QMac will manufacture labels of the form "Labelxxx" where xxx is a sequential number starting at zero. So, for instance, if you compiled the following macro to binary form with QMac: * Delete from the current line to the end of the file ^f10 MacroBegin REPEATIT: DelLine JTrue REPEATIT QMac 2.1 Documentation Page 10 And then converted it back to text, it would look something like this: ^f10 MacroBegin Label0: DelLine JTrue Label0: QMac will generate a separate numbered label for every Jump, JTrue or JFalse command in the macro, even if the labels all exist in the same place. QMac gives you several command-line switches to control the details of how it formats the text macros. You can control the capitalization, use of underscores, indenting, word wrapping, and use of ampersands. None of these controls have any effect on QMac when it is reading text macro file(s), only when it is writing them. The /C switch controls the use of the "continuation" character, ampersand ("&"). By default, QMac does not write this character on the end of lines which are continued (since automatically continues macros on to lines that are indented). However, if you prefer this syntax, you can specify /C+ on the command line to turn this on. You may need to do this if you are sending text macro files to someone using an older version of QMac. The /Q switch tells QMac what your preferred quote mark is for use around quoted strings. The default is /Q+, which means use a double quote mark ("""). By specifying /Q-, you can force QMac to use single quote marks ("'") around quoted strings. The /M switch tells QMac whether you wish to use "mixed case" in command names. The default is /M+, which makes the QEdit command names appear as they do in the QEdit manual (example: ToggleEGA43). Specify /M- to write all lower-case names. Key names are always written in all lower case. The /U switch tells QMac whether to include underscores ("_") in command names. The default is /U-, which means no underscores are written. When /U+ is specified, QMac will insert an underscore before each capitalized letter in a command (as they are capitalized in the QEdit manual). Here is a summary of how commands will look with the different combinations of /M and /U: /M+ /U- (default) MacroBegin BegLine ToggleEGA43 /M+ /U+ Macro_Begin Beg_Line Toggle_EGA_43 /M- /U- macrobegin begline toggleega43 /M- /U+ macro_begin beg_line toggle_ega_43 QMac 2.1 Documentation Page 11 Note that the third option (/M-, /U-) is the way the previous versions of QMac always wrote commands. Again, it matters not which form you use, this is only a matter of personal preference. The /I switch allows you to control the indenting of commands from the left margin. Follow /I immediately by a decimal number to specify the column in which you wish the first command to appear. The default is column 9. The /W switch allows you to control where QMac wraps multiple- line macros at the margin. Follow /W immediately by a decimal number. The default is to wrap at column 80. ERROR MESSAGES -------------- QMac can deal with many errors in a macro text file by skipping either a single command or word, or a whole macro. It will display a warning message indicating this when it occurs, but will not stop. However, if a large number of warning messages occur (by default, 20), QMac will give up processing on that file. If you have some "troublesome" macro files that you need to process, you can set the number of warnings that QMac will tolerate with the /E command line switch. Errors in the input text are always indicated by the row and column where the error occurred, so you can use this to locate the problem. If you use QCP to run language compilers from QEdit, you can install QMac as one of the compilers to take advantage of this. Use the line in QCP.DAT: .qm "qmac $N.mac $F B N >$O" "QMAC " (This assumes that you always use the extension ".QM" on all text macro files). Here is a summary of the possible error messages that QMac can issue. QMac will continue after "Warning"'s but will stop after the first "Error". The following messages are in approximately alphabetical order: Warning: Duplicate definition for label <label_name>. The label named "label_name" was defined in two places. Remove one of the definitions, or change one of the labels names. For now, QMac will use the first definition of the label. QMac 2.1 Documentation Page 12 Error: Error reading input file Error: Error writing output file A DOS error occured on reading or writing the file. Check the file(s), or the disk(s) on which they reside, for problems. Warning: <command_name> ignored inside macro Certain commands, such as MacroBegin, MacroRecord, InputCh and Literal, are not legal inside of a macro (even though they are legal when assigned alone to a key). QMac ignores these, but warns you that it has done so. Error: Input file D:\PATH\FILENAME.EXT does not exist. Based on the direction you specified with /B or /T, what QMac determined to be the input file could not be found. Check the path echoed here for errors. Error: Input file and output file are the same. The two filenames point to the same file on disk, please change one. Error: D:\PATH\FILENAME.EXT is not a valid QEdit binary macro file. When reading from or appending to an existing binary macro file, QMac checks it for errors. If there are problems, the above message will occur. It will also occur if you accidentally specify the two filenames backwards on the command line. It may also occur if you are using an out-of-date version of QMac. If the binary file is too large to load into QEdit, this message will also be issued. Warning: Label <label_name> not found--jump ignored. The label to which a jump instruction pointed could not be found. Check for spelling errors. A do-nothing jump will be inserted in place of the erroneous jump, so the resulting macro may not operate correctly. Warning: Label missing--jump ignored. No label was found after the jump statement. A do-nothing jump will be inserted in its place. QMac 2.1 Documentation Page 13 Warning: Macros cannot be assigned to two-keys. Macro skipped. QMac skipped this macro because it was assigned to a two-key. Warning: Macro contains an infinite loop. QMac found a jump instruction that jumps to itself. Since this would loop forever, it warns you about this condition. NOTE: not all infinite loop conditions are caught by this, just obvious ones. Error: Macro file would be too large for QEdit. Error: Macro too long! The total size of binary macros to be written would be too large for QEdit to load into its internal macro buffer. No binary macros will be written or appended. Shorten your macros, or remove some, and try again. Error: Neither file exists. Neither one of the files on the command line can be found. Error: No macros found in D:\PATH\FILENAME.EXT None of the text in the input file fit the form of a QEdit macro definition. You may get this message if QMac skipped macros in your file due to other errors. Error: Not enough RAM to process macro file. Error: Not enough memory. QMac could not load the binary macro file into memory for lack of space. Exceedingly rare, as most macro files are very small. Warning: Number ignored. (Put '#' in front of ASCII codes). You must precede ASCII codes with '#' as of QMac 2.1. Warning: Only first 32 characters are significant in labels. QMac found a label it thought was longer than 32 characters. It will take the first 32 characters of the name and use that as the label name. Error: Output file D:\PATH\FILENAME.EXT is Read Only! QMac found that the output file is designated Read Only by DOS, and thus cannot be written. Use ATTRIB to change the Read Only status, or choose another filename. QMac 2.1 Documentation Page 14 Warning: Possible truncation of line. QMac found a line that might be longer than 512 characters. This should never occur if you create all your files in QEdit. Warning: Quoted string not closed at end of line. QMac found an opening quote but no matching close on the line. It will close the string at the end of the line and continue. Error: Too many errors. Aborting! After 20 warning messages, QMac will issue this message and halt. This is to avoid cases where hundreds of errors might be caused by a faulty input file. The number of warnings QMac will tolerate can be controlled with the /E command line parameter. Warning: Too many jumps--ignored. There is a limit of 32 jumps per macro. If this is exceeded, subsequent jumps are replaced with "do nothing" jumps. Remove or consolidate some jumps and try again. Warning: Too many labels--ignored. There is a limit of 32 labels per macro. This message may come up when processing a label, or when processing a jump. Remove or consolidate some labels and try again. Warning: Unknown command <command_name> skipped. A command "command_name" was found in your macro, that is not recognized as a valid QEdit command. Either it is misspelled or you are using an out-of-date version of QMac. Warning: Unknown key <key_name> skipped. A key "key_name" was found, that is not recognized as a valid QEdit key name. Either it is misspelled, or you are using an out-of-date version of QMac. Error: Unrecognized command switch 'x' A switch "/x" on the command line was not recognized. QMAC ? at the DOS prompt will print a summary of supported switches. QMac 2.1 Documentation Page 15 Warning: Unsupported op-code <xxx> in binary macro input. An unrecognized code was found in the binary macro file. Either the macro file is damaged, or you are using an out-of-date version of QMAC. Error: /X value not specified. The numeric value following a /I, /W or /E switch must IMMEDIATELY follow the switch, with no spaces between. ACKNOWLEDGEMENTS & CONTACTS --------------------------- Special thanks to Karl Brendel, who wrote the original 1.x versions of QMac. If you have any questions or suggestions, please contact: SemWare 4343 Shallowford Road Suite C-3 Marietta, GA 30062-5003 Voice Phone: (404) 641-9002 9 a.m to 5 p.m. E.T., Mon-Fri. BBS Phone: (404) 641-8968, 2400 bps, 24 hours REVISION HISTORY ---------------- Version 2.08 - 17-Nov-1989 Complete rewrite. Faster. Better error checking. Key names must be in column 1. Ampersands made optional. ASCII codes supported. Comments made more flexible. Now accepts lines up to 512 characters long. Many command line options added. Version 2.1 - 27-Feb-1990 Now require "#" preceeding decimal ASCII codes. Jump, JTrue, JFalse supported. New commands in QEdit 2.1, QEdit TSR 1.1, and QEdit for OS/2 1.5 supported. * * * end * * *