The documentation to GEMTrade v2.3 November 13, 1998 by Mark Wherry mark_wherry@cix.co.uk Contents ======== 1 Introduction 2 Installation and Requirements 3 Using The Program 3.1 The Menu 3.1.1 GEMTrade-Menu 3.1.2 File 3.1.3 Edit 3.1.4 Language 3.1.5 Help 3.2 The Main Dialog 3.2.1 File Translation 3.2.2 Lookup 3.3 Options 3.3.1 Paths 3.3.2 Protocols 3.3.3 Translation 3.3.4 Sounds 3.4 Statistics 3.5 User Dictionary 3.6 Register 4 GEMTrade as a CAB Module 5 GEMTrade and GEMScript Appendix ======== A Contact Me B English Distribution C American Distribution D Legal E With Thanks To... F History 1 Introduction *************** Everyone knows about the brilliant Ruftrade German to English translating program; it's a valuable tool in the Atari world, where a high percentage of documentation is written in German. However, there is just one problem, it is now no longer in development. The biggest flaw with the original Ruftrade program was the user interface, which has been described as "a necessery evil"! With this in mind, and the fact the dictionary was not updateable, Joe Connor tempted (!) me with the idea of rewriting the program with a GEM interface and loadable dictionary. As someone always willing to under take a challenge (ha,ha) ;-) I said I'd have ago. Here is the result..... GEMTrade uses the original Ruftrade dictionaries, but the translation routines have been rewritten. A standard GEM interface has also been added sporting windowed dialogs, help bubbles, OLGA support, AV protocol support and much, much more. Atari Computing helped to support this project, and I hope you like the result. However, the future of the program is now in your hands. While myself, Joe and Atari Computing are keen to continue support; we might get a little disgruntled if nobody registers..... It has taken months of hard work to get this far, so please, if you do use the program, do take the time to register. You will not only be supporting this project; by registering, you will encourage Atari Computing to get invloved developing similar enterprises. Thankyou. :-) As an incentive to register, the unregistered version has the following limitations: ù The number of words that can be translated is restricted to 1000. ù Annoying dialog when the program is executed. ù User options cannot be saved. ---------------------------------------------------------------------- For details of registering look at English distribution, or American distribution. 2 Installation and Requirements ******************************** _Installation_ Installation is very easy. Simply copy the file GEMTRADE.TOS onto your hard drive and then double click it to extract the GEMTrade archive. If you are a single floppy drive user who would like a packed version of GEMTrade that does not need extracting, please contact me. *Note: In version 2.x you may copy the GEMTRADE.INF file as it is no* *longer path sensitive. Registered users must not pass on GEMTRADE.INF* *files when distributing GEMTrade though.* ---------------------------------------------------------------------- _Requirements_ GEMTrade should run on most Atari-compatible systems with at least 1Mb of memory and a ST-HIGH display. A hard drive is not essential, but highly recommended. ---------------------------------------------------------------------- Although not essential, GEMTrade can make full use of the following system extensions: ù BubbleGEM, to provide handy help bubbles for instant information about any of the program's functions. ù OLGA, to support object linking. For example, select a source file, edit it in an OLGA aware editor (Everest, QED, ...) and when you save, GEMTrade will automatically translate the file. Note: In version 2.2, OLGA is temporarily unavailable - sorry if this causes any problems. ù Start-Me-Up, which maintains a document history list of previously used documents, including those handled with GEMTrade. Note: In version 2.2, the DHST protocol is temporarily not available - sorry for any inconvenience. ù GEMJing, to allow sound samples to be played for various GEMTrade actions. ù Any desktop that supports the AV-Protocol, for file dragging, etc... Please see the program's individual documentation for installation details. 3 Using The Program ******************** GEMTrade hopefully provides an easy to use graphical user interface, which is highly compatible with all the modern trends. If you need assistance you can call the hypertext help file by clicking the help button in the relevant dialog, or by using the help menu. Alternatively, a right click with the mouse button over an object will, if BubbleGEM is installed, providea handy help bubble describing what that object's function is. GEMTrade now supports the BubbleGEM help daemon. If this is activated in the configuration CPX, hovering the mouse over an object will also display a help bubble. If you wish to disable GEMTrade's support for BubbleGEM, you can do so in the Protocols sections of the Options dialog. 3.1 The Menu ============= The GEMTrade menu bar provides access to some of GEMTrade's features. Many of these do the same as clicking on the relevant icon, but some functions can only be called from the menu bar. 3.1.1 GEMTrade-Menu -------------------- _About GEMTrade..._ Displays a dialog containing information about GEMTrade. The button to register GEMTrade is also found here. ---------------------------------------------------------------------- Any other accessories you have installed on your system should also be accessable here. 3.1.2 File ----------- _Open_ Opens a file selector to choose the source file. This is the same as clicking on the source button in the main dialog. ---------------------------------------------------------------------- _View Source_ Loads the source file into the selected viewer. This is the same as clicking on the source-view icon in the main dialog. _Edit Source_ Loads the source file into the selected editor. This is the same as clicking on the source-edit icon in the main dialog. _View Destination_ Loads the destination file into the selected viewer. This is the same as clicking on the destination-view icon in the main dialog. _Edit Destination_ Loads the destination file into the selected editor. This is the same as clicking on the destination-edit icon in the main dialog. ---------------------------------------------------------------------- _Statistics..._ Opens the Statistics dialog. _Translate_ Translates the source file into the chosen Language. This has the same effect as clicking the translate-file button in the main dialog. ---------------------------------------------------------------------- _Quit_ Exits from GEMTrade. 3.1.3 Edit ----------- _Copy (to clipboard)_ Copies the destination file (if it exists) to the clipboard. _Paste (from clipboard)_ Uses the file SCRAP.TXT on the clipboard as the source file. This is the same as clicking on the source-clipboard button in the main dialog. ---------------------------------------------------------------------- _Options..._ Opens the Options dialog. 3.1.4 Language --------------- _German to English_ Sets GEMTrade to translate a German source file into an English destination file. _English to German_ Sets GEMTrade to translate an English source file into a German destination file. ---------------------------------------------------------------------- Note: This process is slower than translating German to English as the dictionary is indexed sequentially on German words. ---------------------------------------------------------------------- _User Dictionary..._ Opens the user dictionary dialog, which lists the current user dictionary and allows changes to be made. 3.1.5 Help ----------- _GEMTrade Documentation_ Calls this file to be opened by ST-Guide. _Main Window_ Calls this file to be opened by ST-Guide context sensitively displaying information about the main window. ---------------------------------------------------------------------- _GEMTrade Home Page_ If CAB is running concurrently, it will open the GEMTrade homepage in a new web browser window. _Download Latest Version_ If CAB is running concurrently, it will attempt to download the latest version of GEMTrade from the GEMTrade home page. ---------------------------------------------------------------------- If CAB is not available you will see the following alert: 3.2 The Main Dialog ==================== The main dialog appears when GEMTrade is executed. It contains two groups; one for file translation, the other for word lookup. 3.2.1 File Translation ----------------------- To load a source file for translation, you can do any one of four things: ù Click on the button in the source file row, where the filename is displayed, and select the file with the selector that will appear. ù Drag a file from the desktop onto the GEMTrade window, or Appline button, etc... ù Load GEMTrade by dragging a file onto the GEMTRADE.PRG file. Unlike previous versions, when this method is used, the file will not be automatically translated. ù Use GEMScript. ---------------------------------------------------------------------- To translate the chosen source file, simply click the English/German flag, which is the translate button. To change the source and destination language, use the language menu. ---------------------------------------------------------------------- You will notice a variety of small buttons for the source and destination files; this is what they do: Load the file into the selected viewer. Load the file into the selected editor. Use the clipboard (SCRAP.TXT) for the source file. Reset the destination file name to the default. 3.2.2 Lookup ------------- As well as translating files, GEMTrade provides the facilty for looking up single words. This function works both ways, so you can translate English words to German, and German words to English. Simply type in the word to be translated into the editable text field provided, choose the source and destination language in the language menu, and then click on the lookup 'flag' button. The translation is then written in the line below. If the translation was not successful, a message will appear: ú *Word not found!* The translation for the word you are looking up could not be found. ---------------------------------------------------------------------- _Extra Lookup Features_ The lookup editable text fields both support the standard Atari clipboard keyboard shortcuts: ù [CONTROL] + [C] = Copy to the clipboard. ù [CONTROL] + [V] = Paste from the clipboard. ù [CONTROL] + [X] = Cut to the clipboard. ù [CONTROL] + [Y] = Erase. 3.3 Options ============ This tabbed dialog sets various parameters for the GEMTrade environment. It contains four sections: Paths, Protocols, Translation and Sounds. There is a row of buttons along the bottom of this dialog, here is a brief explanation of their functions: *Help:* Calls this file context sensitively. *Expert mode:* If expert mode is disabled, certain options will be greyed out that allow fine tuning of the translation process. *Apply:* Makes the current settings valid without closing the dialog. *Cancel:* Closes the dialog, the recent changes will be ignored. *OK:* Closes the dialog, the recent settings will be used. A common icon to this dialog is the reset button which resets parameters to default values. It looks like this: 3.3.1 Paths ------------ _Viewer_ Specifies the program that will be called when the viewer icon is clicked on. For convenience, ST-Guide is set as the default. If you have set a different viewer and wish to return to the default, simply click the reset button to the right. _Editor_ Defines which program will be called when the editor icon is clicked on. If you've defined an editor and wish to remove it, simply click on the reset button to the right. _GEMJing_ If the path of GEMJing v1.30 is located here, GEMTrade can be configured to play certain sounds for various actions that are performed. See also the Sounds section of the Options dialog. 3.3.2 Protocols ---------------- _Use editor first for document history list_ The document history list is a list of the most recently used files on your system. It can be viewed with an application such as Thomas Much's excellent Start-Me-Up. If this option is set, the translated file will be associated with the editor first, if it is defined. If no editor is defined, then it will be associated with the viewer. _Auto-translate for VA_START_ When a file is dragged onto the GEMTrade window, it is automatically set as the source file. If this feature is turned on, the translation process occurs automatically when a file is dragged onto the window. _Use BubbleGEM in this Application_ You can use this switch to toggle whether GEMTrade supports BubbleGEM or not. This does not affect all running programs globally, only GEMTrade. 3.3.3 Translation ------------------ _Surround untranslated words with marker character._ When translating it may be useful to see some easy indication as to which words haven't been translated. If this feature is activated, the defined character will be written either side of the untranslated word. _View destination file after translation._ If this flag is set, after GEMTrade has translated the source file, it will automatically display the destination file in the viewer. _Translate text between < > characters._ When this flag is set, text between < > characters will be translated. The reason why you will need to disable this sometimes is if you were to translate HTML files, where commands are written between the < > characters. ---------------------------------------------------------------------- If expert mode is enabled, the options at the bottom of this card will become enabled: _Word in word translation._ When this is enabled, if GEMTrade cannot translate a word it will search within that word, up to the minimum word length set (which defaults to 4), to try and find a match. If this value is set, the translation process will take slightly longer. Similarly, the lower the minimum word length, the longer the translation will take. 3.3.4 Sounds ------------- If GEMJing is available, sounds specified in this dialog will be played when certain actions are performed within GEMTrade. 3.4 Statistics =============== This dialog will display information about the last document to be translated: 3.5 User Dictionary ==================== While GEMTrade has a comprehensive embedded dictionary, it may not always contain some specialised words that you require. Because of this, GEMTrade allows you to maintain a user dictionary of words that you can specify. To edit the user dictionary, choose "User Dictionary..." from the "Language" menu. The following dialog will appear: The upper part of this dialog displays the current user dictionary, and is indexed in alphabetical order by the German word. Notice how the currently selected entry also appears in the text fields, ready for editing. ---------------------------------------------------------------------- _Adding a word_ To add a word to the user dictionary, clear the edit fields and type in your own word with the appropriate translation. Now click "Add Word"; the new word will be added to the dictionary and displayed in the list. _Removing a word_ To remove a word, select the word you wish to remove and click the "Remove Word" button. There is no going back once this button has been clicked. _Editing a current entry_ To edit an existing entry in the dictionary, select the word you wish to change- it will appear in the text fields. Enter the alterations, but instead of clicking "Add Word", click on "Fix Word" instead. The dictionary will the be updated. 3.6 Register ============= Naturally, this is the most important part of the program, and you will probably be anxious to know what to do ;-) The registration dialog is displayed by clicking on the "Register" button in the about dialog. Simply enter your details exactly as they appear on the registration card supplied with your master disk, and click on the "Register" button. If you entered the details incorrectly, nothing will happen! Try entering the details again, paying particular attention to the case of the letters. If you are still having problems, contact me. If the dialog closed, the registration process was successful. You should now see your user name in the about dialog, and the register button should appear greyed out. 4 GEMTrade as a CAB Module *************************** As well as functioning as a stand alone program, GEMTrade can also be used as a module for the CAB internet web browser (version 2.5+). What this means is that if you encounter a foreign web site, GEMTrade can be activated and the page will reformat in English or German. Pretty neat :-) To install GEMTrade as a CAB module, make sure the following files are put into CAB's "Modules" directory. ù GEMTRADE.APP ù GEMTRADE.RSC ù GEMTRADE.MDL ù GEMTRADE.INF (if available) ù GEMTRADE.GUD (if available) *Note:* It is now alright to copy the file GEMTRADE.INF to another location on your drive. Now when CAB is run, GEMTrade can be called upon to translate the page that CAB is currently displaying. To do this, go to the "File" menu and highlight "Modules". When the submenu appears select "GEMTrade". Alternatively, when you right click on a link, "GEMTrade" appears as an option on the pop-up menu. If it is selected, the page given by the link will be translated and then loaded into CAB. *Note:* GEMTrade will appear greyed out if the link you right click on is not a local file. To translate a page not located locally, it must first be displayed in a CAB window. 5 GEMTrade and GEMScript ************************* The GEMTrade program can now be controlled autonomously via the GEMScript protocol. To do this you will need a GEMScript interpreter such as Scripter or Simple Script. The latter is enclosed on the master disk and you should read the provided instructions for details on how to use it. Some example scripts for Simple Script are provided in the SCRIPTS directory on the master disk. You should look at these before trying to write your own. Note: In version 2.2, support for GEMScript is temporarily unavailable. For more information on GEMScript, you should take a look on-line at the English GEMScript Support Site at: http://www.cix.co.uk/~mark_wherry/ Here are the commands that GEMScript currently supports: ---------------------------------------------------------------------- Standard commands: *Open* Selects the specified file as the source file in GEMTrade. *Quit* GEMTrade will terminate itslef. (No parameters) ---------------------------------------------------------------------- GEMTrade commands: *Translate* Translate the source file (if one is selected). (No parameters) *ViewSourceFile* Views the source file in the the selected viewer. (No parameters) *EditSourceFile* Loads the source file into the selected editor. (No parameters) *ViewDestinationFile* Views the destination file in the selected viewer. (No parameters) *EditDestinationFile* Loads the destination file into the selected editor. (No parameters) *UseClipboard* Sets the source file as the file stored on the clipboard. (No parameters) *SetSourceLanguage* Sets which source language GEMTrade will use. One of the following two strings should be passed: german or english. A Contact Me ************* If you have any suggestions, criticisms, registrations, or just want a chat; here's my address: *Snail mail:* Mark Wherry, 4 Fernpark Close, Topsham Road, Exeter, Devon, EX2 6AW *Email:* mark_wherry@cix.co.uk *URL:* http://www.cix.co.uk/~mark_wherry/ *English GEMTrade Website:* http://www.cix.co.uk/~mark_wherry/gemtrade.html *German GEMTrade Website:* http://www.voja.de/gemtrade/ B English Distribution *********************** If you live in the UK you can purchase GEMTrade directly from the author. GEMTrade is supplied on a single floppy disk, please state whether you require DD or HD, in a CD-style jewel case. This costs œ9.99 inclusive. Alternatively, an email-only registration is available whereby the key will be sent to you by email. This costs just œ7.99 inclusive. *Email:* mark_wherry@cix.co.uk *URL:* http://www.cix.co.uk/~mark_wherry/ *Mail:* Mark Wherry, 4 Fernpark Close, Topsham Road, Exeter, Devon, EX2 6AW C American Distribution ************************ If you live in America you can purchase GEMTrade via Systems For Tomorrow. The American version includes a printed manual instead of a CD-style jewel case, please inquire about the latest pricing. *Email:* sales@SystemsForTomorrow *URL:* http://www.SystemsForTomorrow.com *Telephone:* (816)833-4738 or (800)875-4943 (orders only) *Fax:* (816)252-3611 *Mail:* Systems For Tomorrow, PO Box 3034, Independence MO, 64055, USA. *Retail:* 11006 East Winner Road, Independence MO 64052, USA. D Legal ******** _Disclaimer_ The user uses this program at their own risk! I, or anyone mentioned in this document, are not responsible for any damages you may suffer through the use of the program. _Copyright_ This program (with it's associated files) and documentation are the copyright of Mark Wherry. You are not allowed to alter this distribution in any way. *The UNREGISTERED version may be distributed freely, so long as the* *file GEMTRADE.INF is never copied!* _Exceptions_ ù OLGA and BubbleGEM are written by Thomas Much. ù ST-Guide is produced by Holger Weets. ù GEMJing is a program by G”tz Hoffart. E With Thanks To... ******************** There are a few people I'd like to thank for their help in developing this program: *Joe Connor*: For starting me on the project, helping with the German language, updating the dictionaries, designs for the dialogs and the "sexy" icons, testing, testing, testing, ..... and, err, patience ;-) *Thomas Much*: For writing the ObjectGEM application framework used to create this version of GEMTrade. Also, for all the help in using ObjectGEM and for feedback. *Alexander Clauss*: For helping me to allow GEMTrade to function as a CAB module, and for testing and feedback. *G”tz Hoffart*: For giving me some example GEMScript code, suggestions, and for writing the excellent compatible GEMJing sample player. *Kent Kordes*: For his interest in distributing GEMTrade in America. *Volker Janzen*: For setting up the GEMTrade German web pages and translating GEMTrade into German. *Didier Briel*: For his detailed suggestions :-) feedback, and working on the GEMTrade dictionaries. *Dirk Hagedorn*: For his excellent UDO6 system- I would never create documentation without it! *Peter West*: For suggestions, feedback, and the debugging of the hypertext! ;-) *Paul Jones*: For suggestions, feedback, and making me like Macs even more... ;-) And all the users of the program who have given valuable feedback, including: Derryck Croker, Mike Kerslake, Gary Bell, Ryan Edwards, H Cooper, Charles Stanley, Carl Turner and Bill Jackson. (Apologies to anyone I've forgotten - I appreciate your help to! :-) ---------------------------------------------------------------------- Igor Stravinsky for providing the firebird, John Williams for his leit motif, Micheal Nyman for not driving a Mazda car and Mike Oldfield for his programmatic style ;-) F History ********** *Version 1.00beta1 (17/10/97) - beta7 (20/04/98)* ù Many revisions, redesigns, etc.... *Version 1.00 - (05/05/98)* ù First official release version. ù Finally compatible with MagicMac! *Version 1.05 - (14/05/98)* ù Bugfix: A maximum 640x480 resolution was hard wired in for dragging the lookup word. ù Bugfix: Two icons had not been properly defined for mono resolution. ù HTML handling improved - GEMTrade will now ignore text within an HTML tag. *Version 1.10 - (28/05/98)* ù GEMTrade will now handle html definitions. If the word still can't be translated, the definitions will be left untouched so they can still be displayed properly in CAB. ù Installation program added. ù Left [SHIFT] key can be held down whilst loading, to auto- translate and display the clipboard file. *Version 2.00 (Preview Release 01) - (31/07/98)* ù Main dialog redesigned. ù Ported to Pure-C. ù WDIALOG routines are now used instead of FLDLIB. ù Parser functions partially rewritten. ù Bugfix: GEMTrade had problems with long lines. ù Bugfix: GEMTrade had problems with tab characters. ù Bugfix: DHST routines had hard-wired test path left in. ù Bugfix: Paths with directories that had '.' characters produced errors. ù Bugfix: Filenames with no extensions caused problems. ù BubbleGEM help daemon supported. ù GEMTrade allows English->German translation. ù Bugfix: Dialogs looked terrible under TOS!!! :-) ù Bugfix: GEMTrade now works under TOS 1.02. ù Translation lookup is now an editable text field. ù Bugfix: Display occasionally got muddled. ù Auto-translate features removed, because... ù GEMScript is supported. ù "odd INF file handling" resolved. ù User Marker character is now saved in INF file. *Version 2.00 (Preview Release 02)* ù Options, About, and Statistics dialogs redesigned. ù Bugfix: Some ASCII characters were incorrectly set as break characters. ù Bugfix: A few of the colour icons didn't have correct mono versions. ù Right mouse click help bubbles supported, again! ù Iconification on all dialogs. *Version 2.00 (Preview Release 03)* ù More Standard GS commands are supported. ù New startup code used. ù Buttons in Options and Stats dialogs now work properly. ù Escape can again be used to halt translation. ù Control+Q supported. *Version 2.00 - (14/8/98)* ù Version released for Systems For Tomorrow ù Incompatibilities appear to be resolved! :-) *Version 2.01 - (25/8/98)* ù Public (shareware) GEMTrade release. ù Lookup routines tidied up. *Version 2.1 - (21/10/98)* ù Major revision...again... :-) ù Rewritten in Pure Pascal with ObjectGEM. ù Multi-dialogs and menu bar implemented. ù Options dialog redesigned. ù GEMTrade supports GEMJing and can play samples for various actions. ù Web links via CAB added. ù OLGA, DHST, and GEMScript temporarily unavailable. ù Internal viewer added. ù GEMTrade can now copy the translated file to the clipboard (by popular demand :-) ù Compatibility issues finally resolved... GEMTrade should work on anything now! ;-) *Version 2.2 - (29/10/98)* ù User dictionary features added. ù Expert mode added in Options dialog. ù Extra translation controls. ù GEMTrade now looks for help files in it's own help folder. *Version 2.3 - (13/10/98)* ù General spruce up for ACC98.