Copyright 1995, Hyperion Softword ************************************* * Orpheus 2, beta release 2.00.17 * ************************************* Comments and queries to: Hyperion Softword, 535 Duvernay, Sherbrooke, QC J1L 1Y8, Canada tel/fax - 819-566-6296 (Rod Willmot) email - willmot@interlinx.qc.ca Contents of this file: Purpose Usage Registered Users Disk Space Requirements Step 1: The Converter Results of Step 1 What Got Changed Step 2: You and OH.EXE The Reader Interface The Resource Path Updating Script Commands PURPOSE: ======== OH1TO2.EXE (The Converter) is a utility for converting Orpheus 1.nn files to the Orpheus 2 standard. Projects to be converted must be in uncompiled format, not HTX's. OH1TO2 does not delete or overwrite the original project. You should not dispose of the original until you are fully satisfied with your results using Orpheus 2. USAGE: ====== Give the following command at the DOS prompt: OH1TO2 The Converter will take over from there, asking what you want to convert and where you want the new version to go. It's safe, easy to use, and interactive. As discussed later on this document, it even lets you pause during conversion to free up disk space. REGISTERED USERS: ================= If you are a registered user of Orpheus 1 (any version), and are using a copy of Orpheus 2 received from any shareware source (BBS, Internet archive, CD-ROM, etc), please note that you must obtain a KEY file from Hyperion Softword in order for Orpheus 2 to recognize you as a registered user. Until you do so, anything you compile with the new version will invoke the "unregistered shareware" warning from the Reader. Users who purchased Orpheus 1.64-1.65 at the full price ($79 *US*) will receive a complete upgrade package, including KEY file, when Orpheus 2 is officially ready. If you're happy with Orpheus 2 even in beta form and want your KEY file as quickly as possible, give me a voice call at 819-566-6296 (*never* before 12 noon Eastern Time) and we'll arrange for you to download it directly from me. Why should you never call me before 12 noon? The code I'm trying to write next morning at 6:00 a.m. _may_be_for_you_. Faxes however are welcome at any time, at the same number. Users who purchased earlier versions of Orpheus, or who paid less than the current price in US dollars, will receive an upgrade offer in the mail. Again, if you're in a hurry just give me a call. DISK SPACE REQUIREMENTS: ======================== The Converter does not delete or overwrite any of the files from the original version of a project. The converted (Orpheus 2) version is stored in a different set of directories. This means that if you have an enormous project to convert, and little free disk space, you will need to free up space either before or during the conversion process. Don't panic. Read on. This is a friendly Converter. If you NEED to free up space and are not using a disk-compression system such as Stacker or Doublespace, you will have to offload files onto diskette. If you are not using a disk-compression system, a better method is to compress rarely-used files with PKZIP. Actually the best method in both cases is to do a little house-cleaning... I've never seen a file that didn't beg to be deleted. (We're lean and mean, here at Hyperion Softword.) Once you have told the Converter what you want to convert, and where you want it to store the new version, the program analyzes the original project and estimates how much disk space it will need. As conversion proceeds you can watch the indicators showing remaining free space and space still needed. At any time, you can interrupt processing by pressing the . This opens the "OH1to2 paused" dialog, which has three options: press the again to resume, press to abort conversion, or press to shell to DOS. Use this last option (shelling to DOS) to offload files onto diskette or compress files with PKZIP, assuming you need to free up space. When you return from the shell by giving the "exit" command at the DOS prompt, you'll be back in the "OH1to2 paused" dialog and can resume processing, abort processing, or even shell to DOS again. It's neat shelling out without spending a dime. STEP 1: THE CONVERTER: ====================== The first step is to run OH1TO2 on the project you want to convert. When you start the program the opening dialog asks for the following input: Old Project: [............................................................] New Name: [........] New Path: [............................................................] In the "Old Project" field, enter the full path to the project you wish to convert, ending with the name of the project itself. For example, if you have a TEST project based in the C:\ORPHEUS\ directory, enter "C:\ORPHEUS\TEST". In the "New Name" field, enter the name you wish to use for the Orpheus 2 version of the project. It can be the same as the original if you wish, but you might prefer a different name to avoid confusion, such as TEST2 if the original was TEST. The name can be up to 8 characters long; it cannot include a path or file extension. In the "New Path" field, enter the full path to where you want the converter to store the Orpheus 2 version of the project. This MUST be a different from the location of the original version. If any directories named in the path do not exist, the Converter will create them. For example, suppose you are using C:\OH2 as your directory for your Orpheus 2 program files. You can also use this as the base directory for your converted projects. In this case you would enter "C:\OH2" -- just the path, not the name of the project itself. ->> In Orpheus 2, project directory names are identical to the project name itself; they do not end with an underscore as in Orpheus 1. For example, the TEST project under Orpheus 1 would have a project directory named TEST_, but under Orpheus 2 it would just be TEST. Following our example, using TEST2 as the new name would result in a project directory named C:\OH2\TEST2\. The new project file, TEST2.PRJ, would be stored in C:\OH2\. Once you've filled the Old Project, New Name, and New Path fields to your satisfaction, tab to the "Begin Conversion" command and press . The Converter makes sure everything seems right before going on. The next stage begins with a scan of your old project. The Converter examines every storage directory in it, counting up how many cards you have. Then it displays an estimate of the amount of disk space needed along with the disk space currently free. Since OH1TO2 does *not* delete or overwrite your old project's files, the free space will diminish as conversion proceeds. As discussed above under "Disk Space Requirements", you can pause conversion at any time, then either abort or shell to DOS in order to free up more space. When the conversion is complete, you may see a message warning you about script commands requiring further updating on your part. This is discussed later on under "Updating Script Commands". RESULTS OF STEP 1: ================== During the conversion of your project, you will notice an interesting change in your card's filenames. Under Orpheus 1, the root part of a card's filename was based on the linkword you used when you chose to generate that card. The 3-character extension of the filename was meaningful only to OH.EXE, combining letters and digits in a mysterious representation of a link number. Not only was it impossible for a human being to connect the filenames with link numbers, there was always a potential for two versions of a card to exist side by side -- with the same extension but different root names. Under Orpheus 2, the root part of a card's filename is a hyphenated number representing ONLY that card. In the TEST project, the very first card would be named 1-001.TES. The first part of the number is the same as that of the directory where it is stored, DIR1. The second part of the number represents the number of that card inside its directory. (Directory numbers can run from 1 to 9999. Card numbers can run from 001 to 256.) The last part of the card's filename is a three-character extension based on the name of your project. For the TEST project, this would be "TES". Since all uncompiled cards in an Orpheus 2 project share the same extension, it is impossible for two versions of a card to coexist. You can't get confused, and Orpheus can't get confused. (By the way, link numbers are now identical to card numbers. Instead of a code like "!:" pointing to card "somethng.00P" (I think), the new code would be "1-20", pointing to card "1-020.[ext]". Orpheus has always made it easy to do a whole lot of hypertext without worrying about the mechanics. The trouble with Orpheus 1 was that if something went wrong, the mechanism was inaccessible; you had to be a hacker to get in there and fix it. Orpheus 2 gives you complete and easy access: uncompiled cards are now simple text files, and the connections between links and cards are perfectly transparent. It's harder for something to go wrong, a snap to put right if it does.) Here is an overview of the results of conversion, looking just at card files and directories. We'll follow the example of a project originally named TEST that was based in C:\ORPHEUS, converted to TEST2 in C:\OH2. Original: C:\ORPHEUS\TEST - the Homecard --------- C:\ORPHEUS\TEST.PRJ - Project file C:\ORPHEUS\TEST_\ - Project directory C:\ORPHEUS\TEST_\D1\ - storage directory 1 C:\ORPHEUS\TEST_\D1\SOMETHNG.000 - first "child" card Orpheus 2: C:\OH2\TEST2.PRJ - Project file ---------- C:\OH2\TEST2\ - Project directory C:\OH2\TEST2\DIR1\ - storage directory C:\OH2\TEST2\DIR1\1-001.TES - default homecard C:\OH2\TEST2\DIR1\1-002.TES - another card You can read more about all this (if it appeals to you) in online Help, "Files & Directories". One significant point is that you won't end up with as many storage directories. In Orpheus 1 a storage directory took up to 100 cards; in Orpheus 2 the number is 256. Conversion gives all of your cards new names (and numbers) following the conventions sketched out above. Within your cards, all link references are converted to match those numbers. WHAT GOT CHANGED: ================= Certain features that you may have used in Orpheus 1 have been replaced by more powerful capabilities in the new system. Others have simply changed so much that the Converter can't translate them. And some I just haven't had time yet to plug into Orpheus 2. Text Cards: ----------- If your old projects consist primarily of Text cards, you'll be happy to know that the Converter has translated them 100%. However, if those Text cards included a lot of Crosslinks, you should know that in Orpheus 2, Crosslinks no longer exist as a separate link type. Instead, you can now link as often as you wish to any card, from any card, using the standard links. The Converter changes all Crosslinks to Door links. Though there is no longer a link type called Crosslink, the Link Menu does have a "Crosslink" command. This opens a dialog enabling you to select the existing card to which you wish to link; when you have made your selection, Orpheus finds out what type of card it is (Text, Graphic, or Event) and offers you a choice of appropriate link types for linking to that target. You can also make crosslinks (links to existing cards) manually, by switching to Ascii Mode and typing in the linking codes yourself. If you enter a link type that is inappropriate to the target, such as an Action link to a Text card, the compiler will safely catch the error the next time you compile the card bearing the link. Another effect you may need to deal with concerns Note links. In Orpheus 1, you could exlude all Note links from the finished project through an option on the Project Menu. This is no longer the case in Orpheus 2. Instead, Orpheus 2 offers a new link type called the Private link, which is similar to a Door or Note but is NEVER compiled. If you have been using the Exclude Notes feature, you'll want to change your Note links to Private links. One of the limitations of Orpheus 1, the fact that Text cards couldn't scroll, was turned to good advantage by a number of users. You could "hide" text in the lower part of the 50-line workspace, and produce alternate versions of a work by exchanging the upper and lower contents of a single card. Well, you can still do that if you want -- if you disable scrolling project-wide or for individual cards -- but since there is no longer any limit to the length of a card, the command to exchange upper/lower halves has been toasted. As for More links, they still exist for the sake of users who would rather fight than scroll, so the Converter carries them over unchanged. If you want to recapture a chain of Mores into a single scrolling card, you can do so fairly easily. Obviously it would be nice if I could make the Converter do it automatically, and I certainly could -- but some of you would have to wait even longer just to get a product out the door, and I think you've waited long enough. Action and Init Cards: ---------------------- If your project contains Action and Init cards, the Converter will turn them both into Event cards. There are now only three card types in Orpheus: Text, Graphic, and Event. While Text and Graphic cards represent "places" the end-user can visit, Event cards represent things that "happen". In Orpheus 2 you can link to an Event through an Action link, a button command, or as a Text card's built-in Init or Exit link. Read about these in online Help! STEP 2: YOU AND OH.EXE: ======================= Even if OH1TO2 was able to translate your project fully and correctly, there are so many new capabilities in Orpheus 2 that you will want to explore OH.EXE's menus, dialogs, and online Help to see how you can enhance your work. Open the Project Menu and select Project Options. Fill in the options that didn't get carried over. Press for Help on the subject. In the following sections we'll look in detail at some of things you'll probably be doing to upgrade your work. THE READER INTERFACE: ===================== Orpheus 1 forced you to accept a single user-interface for the Reader. Orpheus 2 gives you nearly complete control over the Reader interface, so much so that you can virtually create your own. However, in working out the code to give you that power I haven't had time yet to add any kind of built-in interface. For example, there's supposed to be a menu system (which you can disable, or call only through a command button or script command), but I haven't added it yet. This may be to your advantage, since by the time I get around to it I may have decided to let YOU decide what actually goes on the menus. (On the other hand, you can create your own popup menus NOW, using the new menu() script command, and call them either from command buttons or Action links in your text.) For the moment, unless your work only displays graphics you will need to look into designing your own Reader-interface for each project. The tools involved are in the Project Options dialog, in particular the Screen Layout dialog which it contains. These let you determine the appearance and functionality of your finished project as it will behave in the Reader. Through the Screen Layout dialog you can create command buttons that do exactly what you want them to do, with the result that when the Reader performs your work it will seem as if the program itself had been developed specially for your application. THE RESOURCE PATH: ================== If you use graphics or other external files in your projects, you will need to tell Orpheus 2 where to find them. In earlier versions this was done using the environment variable ORPHEUS=/G[path], meaning look here for graphics files. Orpheus 2 takes a more flexible approach, letting you set the Resource Path in the Project Options dialog. Besides saving a few bytes of your DOS environment space, this lets you keep the resources of different projects separate (if you want). Enter the Resource Path the same as you would a DOS PATH statement in your autoexec.bat file; for example, if you keep graphics for your projects in c:\art and in d:\draw, your Resource Path would be "c:\art;d:\draw". If your old projects used library files (for storing graphics and so on) you will need to use the FGILIB.EXE utility from your old version of Orpheus to extract the contents of those files into the location(s) given in your Resource Path. This is imperative as preparation for the more interesting steps discussed below, such as drawing new hotspots on your graphics. UPDATING SCRIPT COMMANDS: ========================= NOTE: Earlier versions of Orpheus permitted lines to be commented out in three different ways: by placing a "/", a ";", or even a space at the beginning of the line. Orpheus 2 recognizes only "/" for commenting out lines, and the Converter does NOT do anything about the others if you have used them. While a line beginning with ";" should provoke an error message in Orpheus 2, lines beginning with spaces will be processed normally. If the Converter encounters certain script commands in your project, at the conclusion of processing it displays the following message: "Some of your cards contain script commands or other items requiring a manual update. A complete list of them has been recorded in [prjname].LOG. To refer to this file, load your project in OH.EXE, then open [prjname].LOG through the File Menu." If the new version of the project is TEST2, the LOG file for it would be TEST2.LOG. This is a plain ascii text file containing crosslinks (actually Door links) to the cards you'll need to update. To use this file, start by loading your project into OH.EXE -- the same as you would with the old version. Then open the File Menu, select "Open", and either type in the name of the file or tab to the Files box and select it from the list. If you have converted more than one project, select the LOG file with the same name as the project you have just loaded. Here is a sample LOG file (between the rows of stars) warning about two script commands in card 1-99: ********************************************************************** To navigate to the cards listed below while leaving this file in the current window, hold down the CTRL key whenever you jump from here. See Help for details on using OH1TO2's conversion log and on the various script commands that you may need to update. graphic, hotspot ********************************************************************** If OH.EXE is in hyper mode, the last line will actually look like this: "Card 1-99 graphic, hotspot", with the words "Card 1-99" displayed in the color assigned to Door links. You can toggle back and forth between hyper mode and ascii mode by pressing . To jump to the card in question, move the cursor to the colored linkword by pressing the arrow on the number keypad, or by clicking on the linkword with the mouse. Then, HOLDING DOWN THE CTRL KEY, press the arrow on the number keypad, or click on the cursor. By holding down the Ctrl key for a navigational jump, you tell Orpheus to open the Select Window dialog: this lets you load the target card in a different window, leaving the LOG file where it is. (If you don't do this, you'll have to reload the LOG file in order to check the next card on the list.) In the example we're using, card 1-99 has two script commands to update, graphic() and hotspot(). Let's suppose you were using a graphic stored in a library file, so you used the "lib" command within graphic(), and that your card had two hotspots. The original card would have looked something like this: graphic(lib=yourlib.fgi, picname.pcx, 16, FULL) hotspot(......etc) hotspot(......etc) After conversion, this card would look something like: // WARNING: "lib=" not supported //graphic(lib=yourlib.fgi, picname.pcx, 16, FULL) // WARNING: Redraw hotspot! //hotspot(......etc) // WARNING: Redraw hotspot! //hotspot(......etc) Note that all suspect commands are now commented out, rendering them harmless until you can get to them. Your task now is to work your way through the card, consulting online Help for procedures, supported features, and the correct syntax for each command that has a warning. After finishing one card, assuming there are more to update, switch windows back to your LOG file and jump to the next one on the list. In the remainder of this topic I'll discuss the affected commands in detail, leaving hotspot() to the last because it's the most involved. In all cases, consult online Help by selecting "Script Command Reference" from Help Contents. You will often find interesting new capabilities in commands you already use, along with exciting new commands like menu() and ask(). // WARNING: Update parameters! ------------------------------ The play(), run() and runbat() commands require a change to the way you specify parameters. play() - If you use play() to perform a Fastgraph music string, the entire string must now be enclosed in quotation marks. If the string is too long to fit on one line (a line can be longer than the screen in Orpheus 2), break it into multiple strings separated by commas. The play() command also accepts certain keywords (delay and repeat), and in future may accept filenames of music files to be played through Soundblaster-compatible music cards. (This capability is disabled for the moment because of conflicts with Windows.) run() and runbat() - The command line intended for the DOS command interpreter must now be enclosed in quotation marks. Both commands now accept keyword parameters to control whether you want the Reader to clear the screen and/or swap itself out before performing the command. // WARNING: Verify supported parameters! ----------------------------------------- The lookfor() and jump() commands may not support parameters that you used in earlier versions. Familiarize yourself with the current offerings as documented in online Help. // WARNING: "lib=" not supported -------------------------------- You may have used the "lib" keyword to specify a library file for use with an ansi(), graphic(), or lookfor() command. Currently Orpheus 2 does not support library files, because I'm planning something better. The new system will let you prepare an INCLUDE.[ext] file for each project, listing which files if any to build into your finished project. For example, many projects could assemble into a single HTX file containing not only the compiled hypertext but all of its graphics. The INCLUDE system will give you the same flexibility as library files, without the need to learn an external library program. // WARNING: Not supported unless documented in Help --------------------------------------------------- As of 95-10-24 the following commands were not supported: gbox(), gtext(), hide(), jumplist(), and load(). In most cases I do intend to plug in these commands as soon as I have time. However, at least two capabilities of the load() command have become obsolete: the ability to load a form into the Formfill window, the ability to load an external text file into the FileView window. Forms have been completely superseded by the more powerful and flexible Data Fields feature: you can create Data Fields and link to them in any Text Card, for input and/or output. With the old system, if your project offered multiple forms with similar entry fields (for example, to get the user's name and address), the user had to type in the same data repeatedly in each form. With the new system you can link to a given Data Field wherever you like, so once the user has typed in his name and address in one card, his data will appear automatically in any other card where you have linked to that field. As for the old FileView window (in the Reader), it's toast at the moment, and may stay that way. It was only needed as a kludge to provide scrollable text, but now ANY Text card can be scrollable to any length. // WARNING: Redraw hotspot! --------------------------- If your old project had a lot of hotspots, you'll have some work to do. In exchange you'll get much more precision in the shape of your hotspots, and they will be more reliable. Here's why: hotspots in Orpheus 2 consist of one or more convex polygons drawn on your graphic with the mouse. The resolution of the shape and its borders conforms precisely, pixel by pixel, with the screen resolution at which the graphic is displayed. In addition you get some new capabilities, including the power to link a hotspot to a sequence of script commands in the same card, as opposed to having to link exclusively to other cards. For a thorough discussion of hotspots, do read online Help. In what follows I'll focus on how to go about converting your old-style hotspots to the new system. Since hotspot-drawing involves use of the Simulator, you can also read about this in OHSIM.TXT. Let's work with an example in which you display one graphic and give it two hotspots. For illustration we'll say that one hotspot was linked to a Text card (through a Door link), the other to a Graphic card (through a Graphic link). Supposing that the first card was converted to number 1-99 and the second to number 1-100, here's what you start out with after the initial conversion: graphic(yourpic.pcx, 16, full) // WARNING: Redraw hotspot! //hotspot(, ....old data, now invalid) // WARNING: Redraw hotspot! //hotspot(, ....old data, now invalid) Of course you'll only see the brackets and so on in ascii mode; if you're in hyper mode the words "linkword1" and "linkword2" (or whatever you've got) would be in the colors of Door and Graphic links respectively. Step 1 is to delete the part of your old hotspot command that is no longer needed: the word "hotspot" and the opening parenthesis, then the obsolete data following your link anchor. In other words, KEEP "", but delete the rest. You can also delete the warning lines. Remember that "" should remain in what is now a comment line, where it has a special purpose in helping you navigate your own work while authoring. You can even add to the comment if you wish. Step 2 is to take a jump through each link (in OH.EXE) to refresh your memory about what each hotspot was all about. Step 3 is to compile the card so you can display the graphic and add your new hotspots. The quickest way to do this is to open the Project Menu and give the command to "Compile, Simulate". The hotkey for this is , and you'll use it frequently when making hotspots. This command compiles any cards that you may have added or changed since the last compile, then immediately loads the Simulator to display the current card. Step 4, assuming that your Graphic card has compiled successfully -- in which case Orpheus will load it automatically in the Simulator -- will be to press to tell the Simulator that you wish to create a hotspot. Since the drawing procedure is different in Orpheus 2 (faster and more precise), I suggest you read about it in Help or in OHSIM.TXT before starting. During the drawing procedure you can call press for a reminder screen in case you forget what to do. An important part of the new procedure is that once you have finished a hotspot you are prompted to enter a description of it. Later on when you insert the new hotspot command into your Graphic card, this description will be inserted too, on the line above it. You'll find this helpful if you are recreating numerous hotspots, since the description of each will help you put it together with the original link. Step 5, after you've made one or more hotspots for the current card, will be to exit the Simulator (press ) and open the Link Menu, then select "Hotspots". This brings up the Hotspot dialog, through which you can grab the new hotspot commands from the HOTSPOT.LOG file created by the Simulator. Since this file is overwritten in each new session with the Simulator (when you draw at least one hotspot), you should always extract the contents right away. The final step, now that you've redrawn a hotspot and copied the new command from HOTSPOT.LOG into your Graphic card, is to insert the appropriate link number as the first parameter of the command. (For example, a hotspot linked to card 1-99 would begin "hotspot(1-99, ...).