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 :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ((((((((((((((((( Orpheus 2 {beta} User's Guide )))))))))))))))))) :::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: Last revised: November 8, 1995 TABLE OF CONTENTS ============================================================================== Notice Shareware Acknowledgments Part I - Setup 1. Introduction 2. Installing Orpheus 2 3. Notes for Beta Testers Part II - A Look Around 4. What's New 5. What's Missing Part III - Tutorial 6. Starting a new project 7. Making a Link 8. Navigating Links 9. Importing Text 10. Loading an existing Project 11. Building a finished Product Appendix - How to Order ============================================================================== = Notice = ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: * THIS IS A BETA RELEASE. In using it you automatically become a beta tester. Please see "Notes for Beta Testers" below, even if you do not intend to send in bug reports. * THIS FILE IS NOT A MANUAL. 99% of the documentation for Orpheus 2 is in online Help. (Press in OH.EXE for context-sensitive help from any menu, dialog, or other situation.) I'll write the gentle tutorials as soon as I can, but in the meantime too many users are pleading to work with Orpheus 2 for me to delay it any longer. Trust yourself, plunge in, read Help, browse the menus, read more Help, and keep in touch! * If you have projects developed with Orpheus 1.nn, you can use the included utility OH1TO2.EXE to convert them to the new file formats used by Orpheus 2. See OH1TO2.TXT for more information. Do not mix up Orpheus 2 files with your old files! = Shareware = ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: * Orpheus is currently distributed as shareware. As an unregistered user you are welcome to evaluate this copy for up to 30 days. You may not distribute anything you might create with Orpheus 2, in any way, without purchasing a registered copy. Documents created with an unregistered copy invoke a warning message when performed by the Reader. * The price of Orpheus is $79 US, plus shipping. Yes, you can register with your credit card! For full details please see "How to Order" at the end of this file, or use the order form provided in REGISTER.TXT. * If you purchased an earlier version of Orpheus you are entitled to an upgrade. Users who registered at the full current price of $79 US will receive a free upgrade directly from me, as soon as Orpheus 2 is deemed complete. If you hunger to get ahold of it quicker than that, give me a call. If you are unsure of your status and wish to know what an upgrade will cost (if anything), give me a call. But not before 12 noon. The code I write at 6:00 a.m. *may*be*for*you*. = Acknowledgments = ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: * Warm thanks to the beta testers who have contributed to the story so far: Ray Ballard, Andy Roberts. * Thanks in many tongues to those who have worked so hard to provide translations of the Orpheus Reader (in French, Dutch, German, Italian, and Portuguese): Daniel Marois, Jan Moens, Jurgen Nijhuis, Thorsten Glattki, Giovanni Calesini, Jesus de Paula Assis. * Special thanks to the tireless sysop of Synapse BBS, Daniel Coulombe. * Orpheus uses the SPAWNO routines by Ralf Brown to minimize memory use while shelling to DOS and running other programs. = Part I - Setup = ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: ----------------------- 1. Introduction ======================= What is Orpheus? System requirements What can it do? Windows version Shareware... What is Orpheus? Orpheus is a hypertext authoring system. It is designed for the creation of compiled hypertext documents that can be read with the Orpheus Reader. Registered users may distribute such documents (together with the Reader) any way they please: on disk, over BBS systems and the Internet, or installed on a LAN. System requirements: Orpheus runs on any IBM-compatible PC from the XT on up to the Pentium. Orpheus is currently a DOS-based system, requiring DOS 3.1 or higher; it runs very happily under Windows and OS/2. The authoring program requires a hard disk and at least 512K of RAM; for best performance XMS is desirable. The Reader can run on diskette, and survives on much less RAM. What can it do? Orpheus 2 has a capacity of over 2 million linked nodes in a single document. Text cards can be of any length. Graphics support now includes SVGA modes, and you can display PCX, GIF, and FLI/FLC files. Through script commands you can create a work that interacts exquisitely with the user. You can modify the appearance and behavior of the Orpheus Reader so that it looks like it was custom-programmed for you. Windows version: The code in Orpheus 2 was designed for easy portability to Windows-based programming. As soon as Orpheus 2 is complete, I will begin work on a Windows version of the Reader. Shareware... Yes, Orpheus 2 is shareware, as was Orpheus 1. If you are not a registered user of Orpheus 2, you are welcome to evaluate it for up to 30 days; you are NOT permitted to distribute (in any way) works that you may have created with Orpheus 2. The price of Orpheus 2 is $79 US, plus shipping. If I haven't provided ordering information in this release, please contact me by one of the methods given at the top of this file. NOTE: registered users of Orpheus 1.nn can receive an upgrade; please contact me. ------------------------------- 2. Installing Orpheus 2 =============================== Orpheus 1 users Orpheus 2 "Interim Version" Typical installation Orpheus 1 users: If you have used Orpheus 1 in the past, be sure to install Orpheus 2 in a completely different directory. The only "contact" between the versions should be via the Converter, OH1TO2.EXE, if you intend to convert your old projects to the new system. Orpheus 2 "Interim Version" users: do as above. The file formats of the "real" Orpheus 2 (this one) bear no similarity to the Interim Version. User the Converter to change your Interim projects to the new system (see OH1TO2.TXT). Typical installation: Place your Orpheus 2 files into a directory of their own on your hard drive, such as: C:\OH2 From now on you can use that location as your "working directory" for all of your projects. For example, in DOS you would switch to that directory and start up OH.EXE with the command "OH"; your projects would be based in that directory, with their files all stored in subdirectories created for you by Orpheus. See below in this file for discussion of starting a new project and loading an existing project. --------------------------------- 3. Notes for Beta Testers ================================= Memcheck Debug functions Known bugs Check out UPDATE.TXT for a list of changes, fixes, and new features. Memcheck ============ Beta versions of Orpheus now incorporate the Memcheck debugging tool from StratosWare Corporation. Besides helping you discover bugs, Memcheck will protect your work and your system from unexpected behavior. To activate Memcheck your DOS environment must include the MEMCHECK variable, which is done by giving the following command at the DOS prompt, =before= running OH.EXE: SET MEMCHECK=1 This command can be placed in your autoexec.bat file, or in a batch file used only for running the beta. The following batch file could be named OH2.BAT or BETA.BAT, and would optionally pass a project-name parameter to Orpheus: SET MEMCHECK=1 OH %1 SET MEMCHECK= The last command removes the MEMCHECK variable from your DOS environment, and can also be given manually. Whenever Memcheck encounters a serious memory-related error while you are running OH.EXE, a message box will pop up reporting the problem. Please note what the message says, along with some indication of what you had been doing before the error occurred. When you press a key to clear the message, Orpheus will safely exit. I find that debugging is especially convenient under Windows, i.e. in a DOS box. If the program appears to freeze -- no disk activity, no response to the keyboard -- you can safely terminate it using the Windows trick of pressing Alt-Space, selecting "Settings", then "Terminate". NOTE: Memcheck code is also present in the Simulator and the Reader, but not in Help. Does this have any bearing on whether you can distribute a beta version of the Reader to your users? None at all. Unless they themselves set the MEMCHECK variable on their systems, the Memcheck code does not run. Debug functions =================== Currently the F11 and F12 keys (in OH.EXE) are reserved for debug functions, which vary depending on the current focus. Pressing one of those keys alone or in combination with Shift, Alt, or Control may or may not produce a message box or effect. One function that I RECOMMEND you use from time to time is , which displays the contents of the memory page holding the line at the cursor. To clear the display and refresh the whole screen, press any key. This is an easy way to get a full refresh when something odd has happened during word-processing. More important, the display can show you an error condition that Orpheus hasn't caught, if you know what to look for. Briefly: bytes with an ascii value of 0 are displayed (in this debug function) as ascii 254, a square block. If the memory page includes any unused bytes they will be displayed as a stream of these in bright white on black. If the bright white stream includes any OTHER characters, this is an error condition. Here's what to do: (1) if you can, make a note of what you were doing before the condition arose (reformatting? deleting? block ops?); (2) to wipe out the error condition, press to save the file to disk, then select "Reread" from the File Menu to read in the saved copy. The errant characters will be lost but the rest will be okay. NOTE: In the Reader and the Simulator, pressing pops up a message indicating the amount of free memory in the near and far heap. This will not of course happen in non-beta releases of these programs. Known bugs ============== The only bugs currently known to me are in OH.EXE's word processor, affecting some block operations (column move, occasionally a stream block, never to my knowledge a line block) and autoreformat. Also, in some circumstances a multi-line delete at the end of a card causes the cursor to think it's on the wrong line. The best way to clear any such problem, short of exiting the program, is to press (using the middle keypad), which jumps to the top of the current card and resets the cursor position. With the exception of autoreformat and column block moves I've made heavy use of most of the word-processing functions in the course of developing the online Help -- nearly half a megabyte of text before compression. The linking and project-building functions, as well as Help, the Reader, and the Simulator, perform beautifully. Areas of the Reader that need pushing (to see what's missing and what might break) are the script handling, especially with graphics. = Part II - A Look Around = ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: --------------------- 4. What's New ===================== Ascii file format Scrollable text Better linking System capacity Better compiling Improved compression Simpler Reader Customize Reader interface Disable Reader elements Selector keys in Reader Extended graphics support Hotspots improved Menu() command Ask() command Run() & Runbat() improved Data Fields Color schemes The Simulator * Ascii file format: Uncompiled cards are now plain text files. This means that you can create them with any text editor, though more commonly you'll switch into ascii mode (within OH.EXE) for plain-text editing. In ascii mode you can see the link codes and edit them manually (it's easy). The great advantage of the new file format: if something goes wrong, you can fix it. In Orpheus 1 the files were semi-binary, and trouble meant trouble. * Scrollable text: Text cards can be scrollable if you wish, with no restriction on length. Many users of Orpheus 1 liked the screen-sized cards, and you can still use them if you don't like scrolling, or limit scrolling to particular cards. * Better linking: First, link numbers now correspond in a perfectly obvious way to the filenames of the cards they point to. Second, linking itself is more flexible, and as mentioned above, easy to do manually in the rare cases when you need to. Crosslinks (as a link type) are toast; now you can link anywhere as often as you want, using the standard link types. There are several new link types, including Exit links (actions to perform when a user leaves a card), Private links (they don't go into the finished product), Report links (to print instead of the card shown onscreen), and more. Orpheus two extends the use of link codes to handle embedded labels and hilites; both dress up the text with color, and labels can also be used as link targets. * System capacity: The new system is built to handle over 2 million unique nodes, i.e. individual linked cards, of which Text cards can be of any length. Finished products are designed for extremely fast performance in the Reader, no matter how large the work. * Incremental compiling: The old system combined all phases of finished- product-making into one process, which you had to repeat from the beginning if an error was encountered. Orpheus 2 separates "building" into three stages: compiling cards into their individual finished, compressed form, in which they are stored in CMP files; verifying the links to all possible cards in the work, starting from the Homecard; assembling all compiled cards (and other elements) into a finished product. The first stage, compilation, can now be performed incrementally; once a given card has been compiled you no longer have to recompile it, no matter how often you compile new cards or assemble versions of the finished product. This is a huge time-saver. * Improved compression: Finished products are now significantly smaller than under Orpheus 1, particularly if you take advantage of the ability to use scrollable text (as opposed to stringing together many screen-sized cards using "More" links). Along with this there is better security: whereas an HTX compiled with Orpheus 1 could be deciphered without difficulty, and certain parts could be left in plain text, under Orpheus 2 an HTX file looks like 100% binary garbage. Any part too small to compress efficiently is encrypted. *Improved distribution: In terms of finished output, the old system produced a small HTX file with at least one numbered subfile; subfiles were limited to 64K. Orpheus 2 lets you set the maximum filesize up to 1 megabyte, which includes the HTX file. This means you can now assemble most projects into *one* file, the HTX, for simpler distribution. * Simpler Reader: The old Reader had a number of automatic features that, while intended to be friendly, could be troublesome. For example, the user could always open the menu system and shell to DOS, which could be dangerous if the Reader was being used on a BBS. Currently the Reader for Orpheus 2 is "missing" a lot of stuff that made the old one stand out, but it's clear that =authors= will be happy that the Reader no longer forces it on them. In keeping with this, whenever I add an interface-related feature to the Reader I will make it possible for authors to hide or disable it. * Customize Reader interface: You can customize the Reader interface (primarily as evidenced in text mode) in a number of ways. Open the Project Menu, select Project Options, then dig into the Screen Layout dialog. Read online Help about this and about making command buttons. You can make an interface all your own; an example is Help itself, which is NOT hard-coded into the Help engine, rather it was set up as the Help project's layout, and you can do the same with your own projects. * Disable Reader elements: All of the built-in Reader elements (like the menu system, which =will= eventually get built in again) can be disabled through the Project Options dialog. You can also disable the hotkeys (like the one to exit the Reader) and force the user to do things through your own popup menus and/or command buttons. * Extended graphics support: Orpheus 2 now supports SVGA graphics up to mode 29. You can display GIF graphics as well as PCX, and I've added support for animation using FLI/FLC files. * Hotspots improved: Hotspots now are drawn as convex polygons rather than blocky shapes; the new method gives you the same resolution as the image onscreen, making for real precision. In addition, hotspots can be "linked" to a sequence of script lines immediately following a hotspot command; you are no longer limited to linking hotspots to other cards. * Menu() command: the new script command menu() lets you display a popup menu; you can respond to the user's menu selection to call various internal Reader functions, to perform other script commands, or to initiate a hypertext jump. * Ask() command: the new script command ask() lets you display a popup dialog, similar to a standard Orpheus dialog. You can respond to the user's selection with the same flexibility as described above for the menu() command. * Run() & Runbat() improved: control whether the Reader swaps itself out before performing the command (e.g. if you're launching a very large external program you'd want the Reader to swap out). You can also control whether the Reader clears the screen; this lets you use these commands for special effects while displaying graphics. * Color schemes: Colors are now stored for three video standards -- mono, grey-scale, and color -- and if you have all three available while working you can select your own schemes for each and keep them in a single CFG file. The colors active on your system when you assemble a finished product are built into the HTX. If you selected "Your colors" in Project Options, the user sees your work first in your colors; otherwise the default colors appear. However, if the user has a Reader CFG file present, he sees with his own colors, but can still call yours through the Color Dialog -- if you give him access to it. * The Simulator: As a complement to incremental compilation, Orpheus 2 gives you a way to experience your work as if you were seeing it in the Reader, but without having to produce a finished copy of it. The Simulator works with CMP files (described above) -- the stored compiled forms of your individual cards. The Simulator lets you test scripts realistically, and is the environment you'll use for drawing hotspots. ------------------------- 5. What's Missing ========================= A number of useful features that were in Orpheus 1.65 haven't been plugged in yet; a few are now obsolete and won't be. In OH.EXE, anything dimmed on the menus is obviously not ready yet. I especially miss Search/Replace during my work on online Help, so that's high on the priority list. The system will not be complete until you can redefine the keyboard and create macros; Orpheus 2 was designed to facilitate them, and they're coming. Currently the only graphic file formats supported are PCX and GIF, with FLI/FLC for animation. I should be able to add SPR and the new PNG format as I can get the code. Many Orpheus 1 users took advantage of the ability to store graphics etc in library files; Orpheus 2 will replace this by optionally including them in the actual finished document. It will be a whole lot easier, simplifying script commands and eliminating the need to figure out a library-management program. It's all designed, just not coded yet! Look for INCLUDE on the Project Menu, in future releases. Missing from the Reader currently are 90% of the gadgets that were in Orpheus 1.65: a Notebook, a Bookmark dialog, a Tour capability, and of course the built-in menus giving access to these things. The only gadgets in there right now are the Print and Color dialogs, which can only be accessed if you provide your own command buttons. Many authors will be delighted with this situation. I do plan to work in most or all of the gadgets (improved of course), but authors will be able to hide or disable them -- a fundamental feature of Orpheus 2. Speaking of the Reader, a very high priority around here is to provide versions of the Orpheus Reader in French, Italian, Dutch, Spanish, German, and Portuguese, others if users will help with translation. Those listed will be ready soon! = Part III - Tutorial = ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: --------------------------------- 6. Starting a new project ================================= Start up OH.EXE using the command "oh" at the DOS prompt. (Do not give a filename on the command line when you are beginning a new project.) Open the Project Menu and select "New Project". This leads you into a sequence of three dialogs: the first to enter a name for the project, the second to set your project options, and the third to define the project's Homecard. (1) The first dialog prompts you for the name of a new Project File, which must end in ".PRJ". If you enter a name without an extension, Orpheus appends .PRJ automatically; if you include an extension, it must be .PRJ. For example, you can type "TEST" and the new Project File will be named "TEST.PRJ". (2) The second dialog lets you set various project options; these settings will apply only to the current project. The Project Options dialog can also be accessed separately through the Project Menu, and you can set or change any option later on (with one exception) whenever you like. The exception is the "Card Extension" used for uncompiled cards and certain other files; by default it is the first three letters of the project name, such as TES for TEST.PRJ. You can ONLY change it during the sequence for making a new project. For now, enter a title for your work and continue. For online Help about all of your project options, press while in this dialog. (3) The third dialog, Define Card, opens automatically whenever a new card is created. The settings you make in this dialog apply ONLY to the current card, and can be changed whenever you like. For the most part the only item you will regularly concern yourself with is the Topic. Topics are a new feature of Orpheus 2, which you can read about in online Help. A Topic describes the subject of a card; if you make a habit of *always* entering the Topic when making a new card, you will find that you have a rich resource for providing additional forms of access to your work, plus a superb outline for your own use. For now, type in a Topic (such as "Table of Contents") and continue. For online Help about all of your card options, press while in this dialog. With the last dialog concluded, you are in the Homecard of your new project. As shown on the Statusbar (upper right on your screen), the Homecard is named "1-001.TES". The window number, 1, is shown at the left of the Statusbar beside the "Esc:Menu" prompt. The line number at the cursor, 1, is shown to the left of the filename. For an explanation of everything you see on the Statusbar, press and select "Statusbar" from the Help Contents page. At this point you now have the skeleton of a complete project. Using the "TEST" example for illustration, you have a project file (TEST.PRJ), a Homecard (1-001.TES), a project directory with the same name as your project, and the first storage directory for uncompiled cards. Supposing that you installed Orpheus 2 in a directory named C:\OH2, here is what you would have: C:\OH2\TEST.PRJ - project file for TEST project C:\OH2\TEST\ - project directory for TEST project C:\OH2\TEST\DIR1\ - first storage directory in project C:\OH2\TEST\DIR1\1-001.TES - default Homecard for the project If you have been using earlier versions of Orpheus you'll notice some differences here -- for the better. For an explanation of how Orpheus 2 names and stores your files, press and select "Files & Directories" from the Help Contents page. ------------------------ 7. Making a Link ======================== The next step is to begin entering text and making links. If you are new to Orpheus, at this point you might appreciate a little clarification. In some hypertext systems, you start off with a collection of your own existing files and proceed to create links among them; the links might be stored separately in a database, or added to your files in the form of special codes. Orpheus takes a different approach. All parts of an uncompiled Orpheus project are special files created for you by Orpheus and stored in special directories. Hypertext files are called "cards" in Orpheus; they are actually plain ascii text files (in Orpheus 2). What's special about them is that, (1) each begins with a one-line "header" with certain information about it, and (2) each has a unique filename identifying it as a numbered part of the project. For example, the Homecard created in the previous section, if you typed in the suggested Topic, would have a header line something like "OH(TEXT,"Table of Contents")". This means that it's a Text card whose Topic is "Table of Contents". As for the number of the card, in this case 1-001, its significance is that whenever you make a link to that card the target code is just "1-1". You don't have to type in long filepaths that could become invalid, in fact normally you don't type in linking codes at all -- Orpheus does it for you. Whenever you want to add a new part to an Orpheus project, you begin by making a link to a new blank card; then you jump to that card and either type in or import whatever you want that part to contain. Suppose then that you have a collection of text files that you want to turn into hypertext using Orpheus. You'll proceed by importing them, either whole or a section at a time, into card files created on demand as your project grows. You can also compose new material in a card just by typing it -- the heart of OH.EXE is a word processor -- and you can make as many crosslinks as you want between cards in the same project. So let's try this out. Assuming you're in the Homecard, type in something like "Table of Contents", hit a few times to bring the cursor down, and type in "Chapter 1: Excited about Oatmeal". We'll make a link on the chapter title, automatically generating a new blank card as the target of the link. 1. If you are new to Orpheus, put the cursor on the word "Chapter" or click on it with the mouse. If you already know Orpheus, mark the entire title. 2. Now press to open the Link Menu; we'll make this a "Door" link, the standard link type when the target is a Text card. Press to select "Door", and follow the dialogs. 3. If you didn't start off by marking the link anchor, Orpheus will hilite the word at the cursor and let you "resize" the anchor -- extend it left or right to include the whole title. If you did start off by marking it, Orpheus skips this stage. 4. The next step is a dialog concerning the number that will be assigned to the new blank card. Since Orpheus has already figured out the next available number (in this case 1-002), normally you'll just hit here; do it. 5. Now the Define Card dialog comes up. You saw this earlier when you were making your Homecard. As before, Orpheus really wants you to provide a Topic for the card, so type in something like "Why I get mushy over oatmeal". You don't =have= to do anything else in this dialog, but later on, if you want to change some of the "built-in" features of that card, you can open the Define Card dialog through the Card Menu. 6. Finally, one last dialog comes up to select a window for the new card. (To learn about Orpheus 2's window capabilities, press while in this dialog, or select "Edit Windows" from the Help Contents page.) Whenever you create a new card, Orpheus gives you the following options: (a) load it in the current window, replacing whatever is there at the time; (b) load it in another open window, replacing whatever is there at the time; (c) load it in a new window, unless you already have 9 windows open (the limit); or (d) don't load it at all. Note that if you choose options (a) or (b), the existing contents of those windows ARE NOT ERASED, though they are removed from memory. Instead, they're left safely on disk as your cards or other files, and you can get to them again whenever you wish. For the present demonstration, hit to load the new card in a new window. If you've followed step by step through this little tutorial, you are now looking at a blank card linked to the Homecard. Type in something scintillating, like "Some people call oatmeal "porridge", and I just think that's horrid." Press to save your wisdom. --------------------------- 8. Navigating Links =========================== Now for a brief test of hypertext navigation in Orpheus. We'll assume that you have followed the tutorial so far and are looking at card 1-002.TES loaded in window 2 (the window number is on the Statusbar, just right of "Esc:Menu"). Using the number keypad, press the key. This should take you back to your Homecard with the Table of Contents. If it didn't, you have an XT or perhaps a laptop; press the NumLock key to turn on navigation, then press . Note that besides being back in the Homecard, you are also back in window 1. This is because OH.EXE checks whether the card you're jumping to is already in another window, and if so, switches windows instead of reloading the card from disk. Now let's jump through the link anchor you made earlier: click on any part of it to set the cursor there (use the left button for this), then click right on the cursor. Or using the number keypad, press to move the cursor to the link anchor, then press to jump through it. Once again we're in card 1-002.TES and in window 2. Time to find out whether these WINDOWS have anything to do with your hypertext CARDS (they don't). Let's close window 2. Press to close the current window, or go the long way around by opening the Window Menu -- -- and selecting "Close". This puts us back in window 1 and the Homecard, and you can verify that this is the only window by pressing , which opens the Window List dialog. Only window 1 is open. The purpose of this exercise is to show you that your cards have an existence independent of what windows they're loaded in (or not loaded in), and that the links you make are permanent until you change them. To prove it, jump through the link anchor as you did in the previous paragraph. Notice that after the jump you're still in window 1. This time we'll return to the Homecard by using the Retrace method (retraces your steps): click the right button, or press on the number keypad. Now we'll do the jump one more time, but will use a trick to load the target card in a DIFFERENT window. Hold down the key, then do whatever you did before to jump through the link anchor -- click on the cursor after setting it on the link anchor, or press to it then . This time, because you were holding down , Orpheus opens the "Select Window for Jump" dialog. Press to select the offered window, which is #2. To verify that both cards are now loaded in separate windows, press either or a few times (until you tire of switching windows). Each of the 9 edit windows in OH.EXE can hold any text file of any length, including of course your own cards in a project. You can load different windows with the same card, to work with different parts of it. You can hide windows to facilitate rapid switching between those you're working in. For more information, go to the Contents page of Help and click on "Edit Windows" or on "Window" at the bottom. Perhaps right now you're finding all this flexibility a wee bit complicated. Okay, YOU can master it sure enough, but will your eventual readers have to know all this when they get your finished products. No way. The Orpheus Reader offers a much simpler navigational interface and does it all in a single window (the screen!). Moreover, you can customize many aspects of the Reader's functionality, including which keys on the keyboard perform navigation. For more information go to the Contents page of Help and click on "Customizing a Project". ------------------------- 9. Importing Text ========================= In Orpheus 2, you no longer have to load external files into a special Fileview window in order to import text from existing files. All windows are now Edit windows, each can hold any text file of any length, and each file can have its own marked blocks. There are two ways to import text in Orpheus 2: the quick way imports an entire file at once; the slow way lets you import selected blocks. For the quick way, place the cursor on the line where you want the imported text to begin; now open the File Menu and select "Import File", then type in the name of the file to import, or to the Files box and choose it from the list. (Use one of the smaller TXT files for purposes of demonstration.) The entire file is copied into the current card, beginning at the line where you left the cursor. (If there was already text at or below that line, it is moved to the end of the imported material.) To import selected blocks of text you will use a slightly different procedure. Open the File Menu, select "Open", then choose the file to load, such as this one, README.TXT. Assuming you're following this tutorial and haven't filled all 9 windows yet, the file will be loaded into the next available window. README.TXT uses the angle brackets "<>" to indicate keypresses such as . This is an ancient convention decided upon by wizards (at a convention) and I see nothing wrong with it. However, Orpheus 2 uses the same symbols to indicate embedded hypertext links. If you switch windows over to the one containing the Homecard, you can see the link embedded around your chapter title by pressing . Press again to see the link anchor the way we all prefer. What you've just done is toggle back and forth between "ascii mode" (where you see everything just as it is) and "hyper mode" (where embedded codes are hidden and link anchors are colored). If you look at the statusbar to the right of center, notice that a ì symbol (infinity) appears when you're in hyper mode, while a ð symbol (sheaf of papers) appears in ascii mode. Get back into hyper mode and switch windows over to the README.TXT. Scroll or page down a bit, and pretty quickly Orpheus will pop up a message box saying "Incomplete or misplaced link codes". This is because Orpheus tries to interpret what it thinks are embedded link codes, and informs you of what seems to be an error. Press to clear the message; note that Orpheus has switched automatically into ascii mode. NOW if you switch windows back to your Homecard you'll notice that you're still in ascii mode even though your hypertext cards are error-free. (I may change this behavior, but not the next part.) Get back into hyper mode while in the Homecard, then switch windows back to README.TXT. Notice that Orpheus has figured out what you want: the window with README.TXT stays in ascii mode (without an error message) and the windows with your cards stay in hyper mode. Let's see, what were we... Oh yeah, importing text. To import a selected block of text rather than a complete file, start by loading the source file (in this case README.TXT) into another window; you've just done that. Now mark the text you wish to import. The easy way (and the safest if you have a BETA version of Orpheus 2) is to place the cursor on the first line of the text you want, press to begin line marking, scroll down to the end of what you want, and press again to end marking. Now switch windows to one of your cards. Place the cursor where you want to insert the imported text, and press to copy it there. Since that is the Copy-from-window command, Orpheus opens a dialog to let you select the window with the block you wish to copy; there's only one right now, so just press . With the copy complete, press to unmark the inserted copy, or if you've changed your mind (this deletes it). Now return to README.TXT, where your original marked block is still there. Press to unmark it. One final point: if any of the text you import into a hypertext card contains the <> angle bracket characters (for non-linking purposes), you will have to "escape them" before Orpheus will consider your cards error-free. This is a simple matter of inserting a backslash "\", which wizards refer to as an escape code, in front of each such character. You'll also have to do this if you wish to *display* a backslash, i.e. you'll need "\\" in order to see "\". HOT TIP: if you type a <, a >, or a \ while in HYPER MODE, Orpheus automatically inserts the escape code \ in front of it. For more information on linking codes, go to the Contents page in Help and click on "Hypertext Links", then "Codes used in embedded links" or "Using the escape code". By the way, this may be a good time to mention that you can get Help on all kinds of things without having to navigate through Help itself. For example, if you open the File Menu and click the right mouse button (not the left) on "Import File", Orpheus pops up Help on exactly that subject. Or do it with the keyboard: move the menu selection bar to "Import File" and press . --------------------------------------- 10. Loading an existing project ======================================= Before exploring any other facets of Orpheus 2, let's see how to reload your new project in a later session. First, press to quit OH.EXE (or open the File Menu and select "Exit"). At the beginning of this tutorial, you started up OH.EXE with just the "oh" command at the DOS prompt (without any parameters). Now that you've created a project, you can reload it when you start OH.EXE by adding its name to the command line. For example, to reload the TEST project you would enter "oh test". After reloading the TEST project, check your windows and observe that everything is as you left it when you exited. Whenever you quit a project, either in exiting the program or in switching to a different project, Orpheus saves your desktop for the project in a STATUS file, stored in the project directory. You can also start up OH.EXE with "oh", then open the Project Menu, select "Open Project", and type in the name of the project to load. Use the same method later to switch from one project to another. (Since you can only load one project at a time, Orpheus saves the current project's STATUS file, clears all windows, then loads the new project after reading it's STATUS file.) --------------------------------------- 11. Building a finished product ======================================= The one-step Compile Project command in Orpheus 1 has been replaced by the Build Project dialog on the Project Menu. While you can still produce a finished product with a single command, the Build dialog gives you access to the intermediate steps, for an enormous increase in speed and convenience. Users who have worked with certain other hypertext systems are often afraid that "building a finished product" means losing their UNfinished work or the ability to change it. Not so with Orpheus. None of the Build stages has the slightest effect on your uncompiled cards. You can build and distribute a finished version on Monday, make corrections or additions on Tuesday, and send out a new version on Wednesday (or as often and as quickly as you like). With your TEST project loaded, open the Project Menu and select "Build". As you can see, this dialog offers you a number of options, but all of the action takes place with a single keypress, . Normally, you'll leave your options at the most convenient settings: in the Scope box, select "Project"; this means that when looking for cards to compile, Orpheus checks the entire project. In the Selection box, select "Compile if new or changed"; this tells Orpheus not to waste time recompiling cards that have already been compiled. The Options box you can ignore for the time being, but later you may want to increase the "Largest file" setting; this tells Orpheus when to stop adding to one finished-product file and start another. Finally, the Action box is where you tell Orpheus which of the build stages to perform when you press . In the Compile stage, Orpheus compiles your cards into the form they'll have in your finished product: Text cards are compressed, while Graphic and Event cards are transformed from English-language scripts into binary code. Compiled cards are stored in files with a "CMP" extension, one for each storage directory in a project. The Simulator (a simulation of the Orpheus Reader) works exclusively with CMP files. The Verify stage starts out from the Homecard and, using link-records stored in the CMP files, explores every possible link it can find to every card or data field in your project. If a card contains a link to something you've deleted, Verify finds the problem and tells you about it; if a link that should point to an Event card points to a Text card (or vice-versa), Verify tells you about it. At the end of verification a complete list of *everything* needed to go into your finished product is stored in the NODELIST file in your project directory. The Assemble stage consults the NODELIST and puts together your finished product, drawing upon the precompiled parts stored in your CMP files and elsewhere. It is extremely fast. If you make a minor change to a project that has already been assembled, such as a new color scheme, you can reassemble the project (skipping the other two stages) and have a new finished product in seconds. By default, the Action box is set to #1, "Compile only". This is because you have no need of the other stages during most of the development period that you will devote to a given project. Why assemble a finished product you're only half way there? On the other hand, *compiling* should be done on a regular basis throughout development, at the end of the day or when you take a coffee break. No, you don't HAVE to do it, but I advise it, for two reasons. First, as long as the Selection box is set to "Compile if new or changed", you will compile incrementally, catching only those cards that you have added or edited since last compiling. This means that regular compiling doesn't waste you any time, while it does promise extremely fast final-assembly when the time comes. Second, anything that is compiled can be viewed in the Simulator, which looks and behaves just like the Reader when it loads your finished product. (If you use Graphic and/or Event cards, you'll depend on the Simulator to debug your scripts.) Now let's do a test build of the TEST project. For this demonstration I'd like you to change the Action box setting to #4, "Compile->Verify->Assemble". When this is done, press and watch the builder go to work. Fast enough for you? Now let's see what your cards look like in the Simulator. Open the Project Menu and select "Simulate Reader". A message box reminds you that you can hotkey out of the Simulator by pressing . (This is an emergency exit in case you paint yourself into a corner later on: if you disable the default Exit hotkey -- in the English-language version -- and if you forget to provide an Exit command button of your own, you won't have any other out except a reboot.) Once in the Simulator, you'll notice the presence of a titlebar displaying the title of your project and a couple of command buttons. (As of version 2.00.17 the Esc:Menu button does nothing, neither in the Simulator nor if you use it in the Reader. Check the documentation on this if you have a later version.) Important to know right now: YOU DO NOT HAVE TO USE THIS TITLEBAR IN YOUR OWN WORK. Later on, open the Project Menu and select "Project Options", then "Screen Layout". Check it out and press for guidance. You can customize the appearance and functionality of your work in many, many ways. An example is online Help, which as I may have mentioned, was created as an Orpheus project. The appearance of Help, including the command buttons along the bottom row, was set up in the Screen Layout dialog. You can use a frame, a titlebar, a commandbar, and put buttons and topics and your title upon them, but you can also use absolutely none of these, or pick and choose and work up a layout that looks custom-programmed. Exit the Simulator with or . Now let's test your work in the Orpheus Reader, since you assembled an HTX as the end result of your build command. Quit OH.EXE by pressing . At the DOS prompt, start up the Reader with the name of the project as the sole parameter: ohread test The Reader should load TEST.HTX, and it will look exactly like what you just saw in the Simulator. The difference is that, if you are a registered user, you can distribute your HTX with the Orpheus Reader, or install it on a LAN as a corporate (or institutional) information system. Press to exit the Reader. Now you have seen the bare essentials of how to use Orpheus. The rest is up to you. We've touched on only a fraction of what you can achieve with this system, but most of it is as easy as what we've just done. Explore the menus and dialogs, dig into Help, experiment. MAKE STUFF, and keep in touch. Rod Willmot => willmot@interlinx.qc.ca ============================================================================== = Appendix - How to Order = ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::: The following order form is also provided separately in REGISTER.TXT. ORDER FORM Please send me a registered copy of the latest version of Orpheus. I understand that I will receive a Licence granting me the right to sell, give away, or otherwise distribute any compiled electronic works that I create with Orpheus, along with the Orpheus Reader. In accepting this Licence I agree not to compile and distribute works created by others using shareware copies of Orpheus. +=====+=========================================+=======+============+=======+ | Qty | Product Description | Price | Shipping | Total | +=====+=========================================+=======+============+=======+ | | | | US/Can $3 | | | 1 | Orpheus Hypertext Authoring System | $79 US| Other $6 | _____ | +-----+-----------------------------------------+-------+------------+-------+ | | For an affordable site licence, or for a customized version | | | | built to your specifications, please call 1-819-566-6296. | - | +=====+=========================================+=======+============+=======+ * Prices are in US dollars* Total | _____ | +=======+ Name: ________________________________________________ Address: ________________________________________________ ________________________________________________ ________________________________________________ Phone: (work)_________________ (home)_________________ Fax: ______________________ Email: ________________________________________________ Preferred disk format: [_] 3.5-inch (720K) [_] 5.25-inch (360K) [_] 3.5-inch (1.44M) [_] 5.25-inch (1.2M) Method of payment: [_] check or money order enclosed [_] purchase order # ____________________ [_] credit card (see below) *Canadian and overseas orders must be in US dollars, OR the equivalent value in Canadian dollars according to the exchange rate when ordering. I have Version ____ of Orpheus, obtained from: ___________________________ Comments: ________________________________________________________________ ________________________________________________________________ Hyperion Softword 535 Duvernay Sherbrooke, QC Canada J1L 1Y8 *** U.S. customers: Please use a 40-cent stamp on mail to Canada. *** ============================================================================ * Credit Card Orders * ============================================================================ The following information tells how to purchase Orpheus by credit card. Credit card orders are processed by Public Software Library, a fine company located in Houston, Texas (USA). When it receives your order, PSL sends me a fax with your name and address, and I mail you your registered copy of the latest version of Orpheus. From then on you are a customer of Hyperion Softword, receiving information, tech support, upgrades, directly from me. If you need information about Orpheus, call Hyperion Softword, not PSL! PSL cannot tell you anything about Orpheus, but I certainly can. You can reach Hyperion Softword at 819-566-6296 (email: willmot@interlinx.qc.ca). =============================================================================== Credit card order of Orpheus (PSL #11142) from Public Software Library: Fax: 713-524-6398 Voice: 713-524-6394 CIS: 71355,470 Post: Public Software Library, P.O. Box 35705, Houston, TX 77235-5705, USA. * Please enter your name as it appears on your card, * and the address where you receive your credit card bills. Name: Address: Shipping address (if different): Telephone: Fax: Email: Credit card: [ ] Visa [ ] Mastercard [ ] American Express [ ] Discover Card number: _________________________________ Expiry: ________________ Signature: ____________________________________ ===============================================================================