ORPHEUS An Integrated Development Suite For Hypertext Authoring - User's Guide - Copyright 1996 Hyperion Softword Orpheus is a suite of programs dedicated to the creation and distribution of hypertext. The main program, OH.EXE, provides an integrated platform for hypertext authoring. The runtime reader, OHREAD.EXE, is distributed to end-users with works in finished forms. Among the other components, OH1to2.EXE is a conversion program for use by authors wishing to upgrade from Orpheus 1. Orpheus makes you a master of hypertext; it gives you the freedom to explore the multiple dimensions of your subject while bringing them within easy access of your readers; it gives you the flexibility to experiment, to revise and restructure at will; it gives you the power to compose spontaneously in an electronic galaxy, then to release the worlds you have created so that others may experience them. Orpheus is SHAREWARE. This means that you are welcome to evaluate the system, but you may not distribute anything you might create with it without purchasing a registered copy. For pricing and a handy order form, please see the file REGISTER.TXT. Hyperion Softword 535 Irene-Couture Sherbrooke, QC Canada J1L 1Y8 Tel/fax: 819-566-6296 Email: willmot@interlinx.qc.ca 1 ACKNOWLEDGEMENTS: Warm thanks to the beta testers who have contributed to the story so far: Ray Ballard, Andy Roberts, Wim Berden and the guys at ILS, Joost van der Gaag. Thanks in many tongues to all those who have worked on translations of the Orpheus Reader: Daniel Marois, Marc Coulombe, Jan Moens, Jurgen Nijhuis, Paul de Kamp, Thorsten Glattki, Giovanni Calesini, Jesus de Paula Assis, Ernesto Eduardo Casin, Alexander E. Gubin. Orpheus uses the SPAWNO routines by Ralf Brown to minimize memory use while shelling to DOS and running other programs. CONVENTIONS FOLLOWED IN THIS MANUAL: Keystrokes are indicated by <> brackets; for example, means press and release the F1 key, means press and release the "h" key. Combination keystrokes are hyphenated; for example, means press and hold down the Alt key, then press the "f" key, then release both keys. The term "Orpheus" is used both in reference to the system as a whole and to its main component, OH.EXE (the authoring program). Other components are referred to with names related to their function, such as: the Reader (OHREAD.EXE), Help (OHHELP.EXE), the Simulator (OHSIM.EXE), the Indexer (OHINDEX.EXE), and the Converter (OH1to2.EXE). TRADEMARKS Trademarks are the property of their respective holders. 2 --------------------------------------------------------------------------- T A B L E O F C O N T E N T S --------------------------------------------------------------------------- Chapter 1 - Getting Started ......................................... 4 Quickstart ......................................................... 4 How To Use This Manual ............................................. 4 Printing This Manual ............................................... 4 System Requirements ................................................ 5 Installation ....................................................... 5 Upgrading from Orpheus 1 ........................................... 5 Getting Help ....................................................... 6 Chapter 2 - The Orpheus Environment ................................. 7 The Editor ......................................................... 7 Statusbar .......................................................... 8 Using Menus ........................................................ 9 Using Help ......................................................... 10 Using Dialogs ...................................................... 10 Customizing Orpheus ................................................ 11 Chapter 3 - Tutorial : a Hypertext Project .......................... 15 What is a Project? ................................................. 15 How Do You Develop a Project? ...................................... 17 Starting a New Project ............................................. 17 Expanding a Project ................................................ 19 Importing Text ..................................................... 20 Navigating Hypertext in OH.EXE ..................................... 22 What's in a Card? .................................................. 23 Finishing a Project ................................................ 24 3 --------------------------------------------------------------------------- CHAPTER 1 - GETTING STARTED --------------------------------------------------------------------------- Topics in this chapter: Quickstart How To Use This Manual Printing This Manual System Requirements Installation Upgrading from Orpheus 1 Getting Help Quickstart If you're the intrepid explorer type who never reads manuals, go ahead and fire up the authoring program (OH.EXE). Everything you need to know is in the menus and online Help. Browse them both, experiment, have fun. For an explanation of any menu item, click on it with the right mouse button or place the selection bar on it and press . To make sure you get off on the right foot, I suggest you read Chapter 3, the tutorial on making hypertext with Orpheus. How To Use This Manual This manual is a supplement to OH.EXE's online Help. Use it to find out what Orpheus is all about, to get set up, to take your first steps on the path of hypertext authoring. Bear in mind however that all of the detailed information on Orpheus IS in online Help, which you can open at any time in OH.EXE by pressing . You can also run Orpheus Help as a standalone program: give the command OHHELP at the DOS prompt. Printing This Manual If you have Microsoft Write (and if you have Windows, you certainly do), load the MANUAL.WRI version of this document in Write and print it from there. This will give you the best output. Otherwise... set your printer to 6 lines per inch, 12 characters per inch, and use the following command at the DOS prompt: COPY MANUAL.TXT PRN Alternately you can load this file into your favorite word processor, and format and print it however you wish. There are 59 lines per page, with the last line of text at line 55. 4 System Requirements The authoring program (OH.EXE) requires 512K of RAM, DOS 3.2 or higher, and a hard disk. There are no particular video requirements unless you wish to display graphics. For best performance with large projects, XMS memory is recommended but not required. The Orpheus Reader (OHREAD.EXE) requires 340K or more of RAM, depending on the work being displayed, and DOS 3.2 or higher; a hard disk is NOT required. Video requirements depend on the graphical demands, if any, of the work being displayed. All Orpheus programs should run on any IBM-compatible computer, from the late-model XT through AT, 386, 486, and Pentium systems. Orpheus will not run on the PCjr or early XT's. All Orpheus programs run happily under Windows or OS/2. A Microsoft-compatible mouse is required for drawing hotspots in graphics. Installation Orpheus should be installed in its own subdirectory on your hard disk, such as "C:\OH2". You will need at least 1.4 megabytes of free disk space. If installing from disks received from Hyperion Softword, follow the instructions that came with the disks. If installing from compressed files downloaded from the Internet or a BBS, create an Orpheus directory and uncompress them into that directory. Orpheus 1 and Interim Version users: If you have used Orpheus 1 or the Interim Version, be sure to install Orpheus 2 in a completely different directory. The only contact between Orpheus 2 and earlier versions should be via the Converter, OH1TO2.EXE (see below, "Upgrading from Orpheus 1"). Orpheus requires that the DOS "Files" variable be set to at least 15. If your system runs Windows or OS/2 this is guaranteed to be the case. If not, look in your CONFIG.SYS file (in the root directory of your hard disk) for the line beginning "FILES=". Make sure that the number given is at least 15; if you change it, reboot the computer to make the new setting come into effect. Once Orpheus is installed you can work with it in other drives or directories, if you wish, provided you either specify a path on the command line or include the Orpheus directory in the PATH environment string given in your AUTOEXEC.BAT file. If you don't have an AUTOEXEC.BAT file, or don't know how to use the PATH command, consult your DOS manual. Upgrading from Orpheus 1 If you have projects developed with Orpheus 1.nn or the Interim Version, you can use the Converter (OH1TO2.EXE) to upgrade them to work with Orpheus 2. See OH1TO2.TXT for details. 5 Getting Help If you get stuck or need something explained, the FIRST thing to do is to explore online Help. In virtually all situations, pressing calls up context-sensitive Help with an explanation of what you need to do or know. When menus are open, context-sensitive Help on any item can be had by clicking on it with the right mouse button; or move the selection bar to that item and press . You can also run Orpheus Help as a separate program, by giving the command OHHELP at the DOS prompt. If you're still stuck (and have already absorbed this manual), you are welcome to contact me (Rod Willmot) at Hyperion Softword, by one of the following methods: (1) Email (willmot@interlinx.qc.ca) -- this is the best way to get help, report problems, or discuss improvements you'd like to see. (1) Call or fax 1-819-566-6296, preferably between 11:00 a.m. and 11:30 p.m., New York time (generally 7 days a week). I can help best if your computer is up and running with Orpheus loaded. (3) Write to me at Hyperion Softword, 535 Irene-Couture, Sherbrooke, QC, Canada J1L 1Y8. This is the worst way to get help because the turnaround time for me to receive and reply to your letter is simply too long. 6 --------------------------------------------------------------------------- CHAPTER 2 - THE ORPHEUS ENVIRONMENT --------------------------------------------------------------------------- Topics in this chapter: The Editor Statusbar Using Menus Using Help Using Dialogs Customizing Orpheus Orpheus (OH.EXE) is an Integrated Development Environment for creating hypertext documents. Everything you need to compose, revise, and enhance such documents is right at your fingertips. In this chapter we'll take a look at that environment and how you can expect to use it. The Editor When you start up OH.EXE the first time, you will see an empty screen with a statusbar at the top and the cursor in the upper left corner. What you are looking at is a full-screen window in the hypertext editor that is at the heart of Orpheus. You can open 9 such windows. As shown by the "1" on the statusbar (beside "Esc:Menu"), you start off in Edit window 1. In Orpheus 2, uncompiled hypertext cards are simply text files, combining the words you want your readers to see with codes for hypertext links. Since the codes themselves are text, you could use just about any editor to compose an Orpheus project. The advantage of OH.EXE's editor is that, except when you actually want to see the codes, it interprets and hides them, letting you see your work the way your readers will see it, and navigate through it as hypertext even while you are still writing it. As you work on a project in Orpheus, you will typically have from half to all 9 possible Edit windows open, some containing various parts of your project, others perhaps containing external text files that you are using as resources. (Besides composing hypertext, the Edit windows can be used to view or edit text files not belonging to a project.) When you exit OH.EXE or switch to a different project, Orpheus saves a record of the window contents for the project you were working on. The next time you open that project, Orpheus will restore the windows to what they contained before you quit. For more about the Edit windows in Orpheus, check out the Window Menu and read online Help. 7 Statusbar The Statusbar displays a variety of messages and symbols that keep you informed of where you are and what you are doing; some of them can be used with the mouse to switch windows, toggle edit modes, or navigate hypertext. The illustration below represents all of the items that might appear. (See online Help for more thorough discussions of each.) Esc:Menu |*1 | Push Marking IniExiPrvNxtRptMor Wrap | ì |[ 1]| "FILENAME.EXT" 1 2 4 5 6 7 8 9 10 11 12 13 14 16 17 ^3 ^15 (1) Press to open the menu system, or click on "Esc:Menu". To open a specific menu in one step, press with the first letter of the name of the menu, e.g. for the File Menu. (2) A hilited asterisk indicates that the file in the current window has been changed since it was last saved to disk. (3) Item 3 is the number of the current Edit window being displayed. If you click on this number Orpheus switches to the next non-hidden window if any. For other window-related commands, open the Window Menu. (4) The current editing mode is indicated here: "Push" for Pushright means that typing a character pushes any existing text at the cursor to the right; the opposite is "Over" for Overwrite. Press to toggle from one mode to the other, or use the Edit Menu. (5) Next comes a message area, which is normally blank. The illustration displays the "Marking" message, which would appear if you were marking a block of text. If you click on this area (whether blank or not), the Mouse Blocks dialog opens to facilitate block operations with the mouse. (6-11) The central area of the Statusbar is reserved for flags that indicate whether the current card has a certain type of built-in link. These are: "Ini" for an Init link, "Exi" for an Exit link, "Prv" for a Prev link, "Nxt" for a Next link, "Rpt" for a Report link, and "Mor" for a More link. To navigate such a link you can click on the flag or go use the Link Menu. Note that the Reader interface to such links is completely different; for example, Init and Exit links are events that the Reader performs automatically when the user enters or leaves a card with such links. (12) Another edit-mode toggle concerns wordwrap and autoreformat. "Wrap" means that wordwrap is active; "Rfmt" means that autoreformat is active. You can toggle these states either by clicking on the flag, or through the Edit Menu. In ascii mode (see next) wordwrap and autoreformat are ignored, so the flags are dimmed. (13) The final edit-mode toggle concerns hyper mode and ascii mode. In hyper mode, symbolized by a "ì" character, Orpheus hides all linking codes and displays your text link anchors in whatever colors you have assigned 8 to them. In ascii mode, symbolized by a "ð" character, Orpheus displays the real contents of your cards, letting you edit the codes manually if you wish. You can toggle from one to other by clicking on the symbol, or through the Edit Menu. (14,16) Square brackets on either side of the line number indicate that you have set a temporary left or right margin. Pressing sets a temporary left margin at the cursor position; the same keystroke cancels the tempory margin. (15) Indicates the line on which the cursor is positioned, from 1 to 9999. (17) The final item on the Statusbar is the name of the current file. If the file has been changed since you last saved it to disk (as shown by an asterisk beside the window number), you save it to disk by clicking on the filename, or through the File Menu. Using Menus Orpheus (OH.EXE) is a feature-rich program that new users may find a little complex. Fortunately, the menu system makes it easy to find your way around and quickly become an expert. The best way to learn Orpheus is to browse the menus while taking advantage of online Help. For an explanation of any menu item, place the selection bar on it and press , or click on it with the right mouse button. Pressing opens the menu system and preselects the name of the last menu opened. To select a menu, click on its name or press the key corresponding to its first letter, or press after using the arrow keys if necessary to move the selection bar. To accomplish all that with a single keystroke, press with the first letter of the desired menu, e.g. for the Link Menu. Once the menu system is open, you can change menus with the left/right arrow keys; for example, if the File Menu is open, press the right arrow to open the Edit Menu. To select an item on a menu, move the selection bar to it (using the up/down arrow keys) and press . Alternately, just press that item's hilited letter, or click on it with the left mouse button. A very few menu items, such as the first three on the Edit Menu, allow you to change a setting without closing the menu. For example, if you click on "Edit mode" on the Edit Menu, or press or with that command selected, the setting changes but the menu remains open. To close the menu, press or click anywhere outside the menu. While the menu system makes Orpheus easy to learn, keyboard accelerators let you bypass the menu as you quickly become an expert. Accelerators for menu commands are shown right on the menus, while others (for cursor control and so on) are listed in online Help under "Keyboard Shortcuts". If you redefine the keyboard (see the Setup dialog on the Other Menu), you'll notice that the menus reflect any related changes you make, though Help does not. 9 Using Help As mentioned above, Help is available on any menu item. It is also available in any dialog -- indeed, any situation whatever -- by pressing . A particularly useful facility of Help is that you can return to the previous help-topic (after leaving Help) by pressing . This makes it easier to learn new procedures: you can read the instructions for what you wish to do, exit Help and do as much as you can, then press to return to exactly the instructions you were reading before. Virtually all Help topics include hypertext links connected to other topics. The presence of such a link is indicated by a colored word or phrase, called a link anchor. To jump through the link, click on the anchor, or move the selection bar to it and press . Use the and arrow keys to move the selection bar, or to scroll as the case may be. Pressing is the same as , to jump through the selected link anchor if any. Pressing is the same as , to retrace your steps after a series of jumps. You can also move the selection bar by pressing the first letter of any visible link anchor. You may be interested to know that every feature of the Help interface, including the screen design, the command buttons along the bottom of the screen, and even the keyboard interface described above, was decided by me using exactly the same authoring procedures that you will use in working with OH.EXE. Orpheus Help was in fact written as a project using OH.EXE, and the Help interface is encoded in that project, NOT in any program code. The program that performs Help, OHHELP.EXE, is a limited subset of the Orpheus Reader. Though normally it is called from within OH.EXE, you can also run OHHELP.EXE as a standalone program. Using Dialogs Most of what you will do in Orpheus, apart from editing text, is accomplished through dialogs. If you are familiar with virtually any contemporary software, you already know how to use the dialogs in Orpheus. The results of your dialog selections may be applied to immediate acts like making a hypertext link, or may be optionally stored in (for example) a configuration file. All dialogs can be cancelled, and all dialogs have complete context-sensitive Help. In many dialogs, related items are grouped together in boxes. Before the commands or actions in a box can be accessed, the box must be hilited. To hilite a box, click on it with the left mouse button, or move the selection bar with the , , or keys. If you are already in a box and wish to move out of it (to another box or to a non-boxed command), either click on the desired location or use the or keys. (Within a box, and move the box's selection bar, while and do nothing.) To select or activate a command in a dialog, click on it with the mouse or move the selection bar to it and press . Some commands 10 have hilited action-keys that you can press, while others use non-hilited named keys, like . The hilited keys in a box can only be used when you're in that box; similarly, when you're in a box the only hilited keys you can use are those in the box. However, named keys like can be used at any time, whether you're in a box or not. While most dialogs are pretty standard -- select an option and move on -- a small number have a specialized interface appropriate to their special purpose. An example is the dialog for changing colors (see the Other Menu->Setup Orpheus->Change Colors). Just remember that you are never more than a click or a keypress away from online Help. Every dialog's Help topic begins with an illustration of that dialog, with each element and procedure thoroughly explained. Customizing Orpheus Many parts of the Orpheus environment can be customized to suit your preferences, needs and work habits. (You can also customize the appearance and behavior of the Orpheus Reader when it loads your finished project, but that is another topic.) As an overview, this section is designed to encourage you to try to get the most out of the authoring environment -- the most utility and the most enjoyment. Consult online Help for more information when do begin customizing. All customization begins through the Setup Orpheus dialog, which is accessed through the Other menu. Before examining the various items in this dialog, notice that there are two ways to *exit* the dialog: by pressing , and by pressing . With the first method, your new settings are saved to a configuration file named OH.CFG. The next time you start up OH.EXE, Orpheus will read this file to determine how you want things to work. With the second method however, your new settings are not saved to disk -- but they do remain active for the current session. This lets you experiment with various options without committing to them (and of course you can always reconfigure even after saving OH.CFG). The sub-dialogs accessed through Setup Orpheus, such as the Color dialog, all have buttons that really do cancel changes, restoring whatever settings were in effect before you entered that dialog. CHANGING COLORS The Color dialog lets you set up color schemes, not only for your work environment in Orpheus, but for the finished product as displayed by the Orpheus Reader. If you wish, you can store up to 9 different color schemes, called palettes, whether to suit the changing demands of your eyes or to create a different mood for every project. Each time you assemble a finished copy of your work (the version used with the Reader), Orpheus builds into it a copy of your *current* color scheme. Normally the 11 end-user will therefore see your work in the same colors as those in which you created it. This is a very good reason to make sure that you give the user access to the Reader's Color dialog; the colors that you find relaxing or stimulating may be unbearable (or uninteresting) to your intended readers. All Orpheus programs provide color data appropriate to the user's video display hardware, which may be monochrome, grey-scale, or color. Suppose you as an author have a color display: users reading your finished work in color will see the color scheme that you designed, but users with mono or grey-scale displays will see the appropriate *default* schemes. (However, if you have access to all three types of video display you can design and store color schemes for all of them; see Help for details.) PRINT OPTIONS Printing support in Orpheus is intentionally pretty basic. You can make a standard printout, or export a card or Help topic to an external disk file (print to disk). If you need more refined printing, the solution is indirect but simple: use the print to disk feature, then import the resulting text file into your favourite word processor and go on from there. When you use the Print command from the File menu, the Print dialog lets you make temporary changes to your print options before you actually print. To make changes that can be saved to OH.CFG, use Print Options from the Setup Orpheus dialog. VIRTUAL MEMORY Virtual memory is the technique of extending conventional memory resources by means of swapping: copying the contents of an area of memory to another location, such as XMS memory or a disk file, in order to reuse that area for some other purpose. Orpheus uses virtual memory during normal editing and project building, or rather it does so when necessary. If you develop large projects with long text cards, Orpheus will use virtual memory a great deal. In this case you should configure Orpheus to give you the best performance possible on your system. If you have XMS memory available, Orpheus will show this in the lower right quadrant of the Virtual Memory dialog. For best performance, tell Orpheus to use XMS. If you do not have XMS but do have EMS memory, you may be able to achieve performance similar to that with XMS. The trick is to use some or all of that EMS as a RAMdrive; consult MS-DOS Help on RAMDRIVE.SYS (or your DOS manual) if you don't know how to do this. With a RAMdrive set up, return to the Virtual Memory dialog and set the swapfile path to the drive letter assigned to the RAMdrive. 12 The Virtual Memory dialog can also be used to check out how much conventional DOS memory is free for Orpheus to operate with. Ideally, before starting up OH.EXE you should have at least 512K free RAM; you can find this out by running the MS-DOS "mem" command. Returning to the Virtual Memory dialog, check the "low RAM free" report. If it is lower than 48K you may need to free up additional DOS memory if you develop large projects. DEFINE KEYBOARD The Define Keyboard dialog lets you customize OH.EXE's response to the keyboard. This is especially handy for common editing tasks, since you can adapt Orpheus to behave the same as your favourite word processor. Orpheus comes with a small number of built-in keyboard assignments, most of which are accelerator keys for tasks listed on the menus. You can redefine the response to any keypress except and . A complete list of the default keyboard assignments is given in Help under "Keyboard Shortcuts". This list does not reflect any changes you might make, so for an accurate account you must browse the list in the Define Keyboard dialog. You'll notice that changes you make *are* reflected on the menus, where keyboard accelerators are hilited; however, Define Keyboard gives you access to over 60 functions that are not on any menu and in some cases do not even have a default keypress. Note that this dialog only affects the keyboard response of OH.EXE, in other words your working environment as an author. For project-specific control over how the Orpheus Reader responds to the keyboard, see Help under "Customizing a Project". EXTERNAL EDITOR Despite the customizations described above and in the next few paragraphs, you may prefer to use a more powerful (or more familiar) program for serious text editing. Provided you choose a DOS text editor that handles files in plain text format, you can do this quite easily, returning to Orpheus only for tasks related to hypertext. Programs recommended for this purpose include Multi-Edit for DOS from American Cybernetics, TSE from SemWare, and PC-Write. To prepare for use of an external editor, start by going through Setup to the External Editor dialog, where you can set options to be saved in OH.CFG. To actually run the program you will go through the Edit menu and select "External Editor" from there; as with printing, you can then make temporary changes to your options that will not be saved to OH.CFG. Note that the External Editor commands can be applied to *any* compatible DOS program, such as a spell-checker. After running an external program Orpheus checks each Edit window to see whether the file it contains has changed, and if so, loads in the newer copy from disk. 13 CURSORS Use the "Cursors" box to set the appearance (size) of the cursor in Pushright and Overwrite modes. For example, if you are using a laptop and do not have a utility to make the cursor more visible in all programs, you can use this dialog to make the cursor a block. Most users like to use the standard line cursor in Pushright mode and a block cursor in Overwrite mode. TABS Use the "Tabs" box to set the number of spaces in a tab, and optionally to make insert spaces instead of just moving the cursor. MISCELLANEOUS There are three options you can set in the Miscellaneous box. The first, ";Text-card comments", refers to how you want Orpheus to interpret lines beginning with a ";" character. If you select this option, Orpheus ignores such lines during compilation; you can use this feature to make notes to yourself that will not go into your finished work. The second option, "Swap for DOS shell", tells Orpheus whether or not to swap itself out if and when you shell to DOS from the File menu. The swapping code for this function will use XMS, EMS, or a disk file, in that order of preference, depending on availability. If neither of the first two is available and you have lots of conventional memory left over, you may want to leave this option off. The final Miscellaneous option, "Quit restores blink", tells Orpheus whether to restore blink or maintain high-intensity backgrounds when you exit the program. 14 --------------------------------------------------------------------------- CHAPTER 3 - TUTORIAL : A HYPERTEXT PROJECT --------------------------------------------------------------------------- Topics in this chapter: What is a Project? How Do You Develop a Project? Starting a New Project Expanding a Project Importing Text Navigating Hypertext in OH.EXE What's in a Card? Finishing a Project What is a Project? In one sense you already know what a project is: it's that electronic guide, manual, book or infobase that you hope to create and distribute using Orpheus. But in terms of actual files on disk, what form does a project take during development, and what will it look like when finished? Here is a schematic of a typical project, showing directories in in lowercase letters, filenames in uppercase. The illustration assumes that you have installed Orpheus on drive c: in the \oh2 directory, and that the project is named "TEST", but they can be whatever you like. Note that only the first item, the working directory, is created by you; everything else is generated automatically by Orpheus when needed. c:\oh2\ ...the "working directory" (you make this) c:\oh2\TEST.PRJ ...the "project file" for TEST \test\ ...the "project directory" for TEST \dir1\ ...its first "storage directory" \........ ...more storage directories as needed \dir9999\ ...up to 9999 storage directories The place where you begin work on a project (your current directory when you start up OH.EXE) is called the working directory. This is the only directory you set up yourself. You can use the same working directory as the starting point for any number of projects; it can be wherever you installed Orpheus 2. Except for the project file, everything in your work in progress is stored in the project directory and its numbered subdirectories. The parts you will edit yourself -- text you compose or import, and scripts to display graphics or perform various actions -- go into special text files called "cards", which are named and stored as shown below. These really are text files; you can open them with any text editor or file viewer. They are special because of their filenames, and because each begins with a one-line "header" with information used by Orpheus. 15 c:\oh2\test\dir1\1-001.TES ...a "card" file \......... ...more cards generated as needed \1-256.TES ...up to 256 cards per storage directory Card filenames begin with a two-part number separated by a hyphen, and end with a three-letter file extension. The first part of the number corresponds to the directory containing it: in dir1, filenames start with "1-"; in dir2, filenames start with "2-". The second part is a 3-digit number from 001 to 256, corresponding to the fact that a single storage directory can hold up to 256 cards. (In dialogs and linking codes you can leave out the extra 0's; for example, 1-1 is the same as 1-001 for all purposes except filenames.) Finally, the three-letter file extension can be whatever you wish, provided it is the same for all of the cards in the same project; by default, it is drawn from the name of your project. Since there can be up to 9999 storage directories per project, with up to 256 cards per directory, you can have up to 2,559,744 cards -- each of unlimited length -- in a single project. (For comparison, the OH project here at Hyperion Softword, provided for your use as online Help, handles over half a megabyte of text in a mere 120 or so cards.) Naturally, the FINISHED version of your project is much more compact, consisting of one or more files generated through the final assembly stage of the Build process (discussed later in this chapter). Compiled, compressed, and encrypted, these files cannot be edited or changed by other users. However, building a finished product has no effect on the unfinished version of your work; therefore, you can expand and edit a project indefinitely while generating new versions of the finished product whenever you wish. As shown below, your finished work is deposited in the working directory as one or more files named after the project itself. Often there is just one file, normally with "HTX" as the file extension: c:\oh2\TEST.HTX ...distribute this with the Orpheus Reader With large projects there may be additional numbered files: c:\oh2\TEST.HTX ...distribute this with the Orpheus Reader, plus: \TEST.001 \TEST.002 ...up to 999 numbered files if needed If you use the Orpheus Professional option called "Executable HTX", the file that would normally end with an HTX extension is merged with the Orpheus Reader to become a self-opening book: c:\oh2\TEST.EXE ...distribute this only (no separate Reader) \TEST.001 ...plus any additional numbered files if created These illustrations do not show any external files referred to in your work, such as graphics or other programs launched from a script. You would have to keep track of them separately. 16 How Do You Develop a Project? From start to finish, developing a project consists of three phases: starting it, expanding it, and generating a finished version of it to distribute to end-users. (1) The first phase, starting, is very brief. Using the "New Project" command on OH.EXE's Project menu, you tell Orpheus the basics of what to name your project and where to store it. Orpheus then produces certain startup components (files and directories), comprising the seed from which to grow your work in whatever direction you wish. A step-by-step guide through this phase is given in the next section, "Starting a New Project". (2) The second phase, expanding (along with revision and so on), continues indefinitely for as long as you have an unfinished copy of your work. Expanding a project is basically a matter of adding new card files and putting something in them. Normally, this is done through one of several commands on the Link menu that simultaneously generate a new card and add linking codes that point to it from your current location. A step-by-step guide to the most common procedure is given in a later section of this chapter, "Expanding a Project". (3) The third phase, finishing, is as brief as the first -- but can be repeated whenever and as often as you wish. Imagine that you have published a beautiful book, complete with full-color graphics and leather binding. The morning after your launch party you find some typos, or get inspired to write a new chapter, or come across some groovier graphics. With a printed book you'd be stuck; but with hypertext you can just do what you want, tell Orpheus to build a fresh version of the finished product, then have another launch party. All aspects of building a finished version are handled through the "Build Project" command on OH.EXE's Project menu. A step-by-step guide to the basic procedure is given in the final section of this chapter, "Finishing a Project". Starting a New Project In this section we'll go step by step through the process of starting a new hypertext project in Orpheus. Our examples will assume that your working directory is "c:\oh2" and that the test project will be named "TEST". Start up OH.EXE at the DOS prompt using the command "oh"; if using Windows or OS/2 do the same as you would to start up any other DOS program (such as File->Run in the Windows Program Manager). When Orpheus finishes loading you will see its statusbar on the top line, with the cursor under the top left corner, and "?Unnamed?" in the upper right. Now press to open the menu system, followed by

to pull down the Project Menu. (Pressing would do the same in one step.) The selection bar is already on "New Project", so press to select it. This initiates a sequence of dialogs to guide you through the process; at the conclusion of each dialog Orpheus moves automatically to the next. 17 In Step 1, Orpheus opens a dialog with the title "Enter a New Project (.PRJ) Name". If you enter a name without an extension, Orpheus appends ".PRJ" to form the name of the project file; but if you do include an extension, it must be ".PRJ". The root part of the name is then used for the project directory and the other files discussed above. To continue this tutorial, type in "test" and press . In Step 2, Orpheus opens the Project Options dialog. Notice that the dialog title includes the name of your project: settings you make in this dialog apply to the current project only. As you will see, there are lots of things you can do here, in particular customizations of how the Reader will look and respond when it opens your hypertext. Read about these options in online Help. With one exception, you can change any option at any time during the life of a project; just open the Project menu, select "Project Options", and do it. The exception is the "Card extension" item in the group box entitled "Your project". This refers to the file extension that will be used for all of the uncompiled cards and certain other files in your work in progress; you can ONLY change this now, during Step 2 of starting a new project. For this tutorial we'll only make one setting, the "Title" for your project. Type in something appropriate like "Testing, Testing, Testing!" and press . Then press to conclude the dialog. In Step 3, Orpheus opens the Define Card dialog. Whenever a new card is created, this dialog comes up so that you can immediately determine certain properties of that card. (You can change these properties later by selecting "Define Card" from the Card menu.) Since the most common use for this dialog is to edit a card's Topic entry, you start right off at the Topic item. A Topic describes the subject or purpose 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 with which to provide additional forms of access to your work, plus a superb outline for your own use. In this case, Orpheus is generating the Homecard for your project, so it would be appropriate to type in something like "Table of Contents". With the last dialog concluded, you are in the Homecard of your new project. That is, you are in an apparently empty text file that happens to be the project's Homecard. The filename, "1-001.TES" if you are following the tutorial exactly, is shown on the statusbar at the far right. The line number at the cursor, 1, is left of the filename. The current window number, 1, is beside the "Esc:Menu" prompt. And here's what is on your hard disk (details depend on your installation): c:\oh2\TEST.PRJ ...project file for TEST project c:\oh2\test\ ...its project directory c:\oh2\test\dir1\ ...its first storage directory c:\oh2\test\dir1\1-001.TES ...and its default Homecard This constitutes the bare essentials of a project in Orpheus. 18 Expanding a Project In this section and the one following we'll add flesh to your empty Homecard, setting it up like a table of contents. On each of three titles we'll make a link to a new blank card, then will demonstrate three different methods of putting something in those cards. Begin by typing the four lines of text below into your Homecard: TABLE OF CONTENTS How to Read This Book What's New About Orpheus Next, move the cursor to any word in "How to Read This Book". (Since the number keypad is normally used for hypertext navigation in OH.EXE, you should use the middle keypad for cursor movement. Alternately, move the mouse pointer to the desired location and click the left button to set the cursor there.) Open the Link menu by pressing and then , or simply . We'll make the standard link type, which is called a "Door" in Orpheus. Since the selection bar is already on the Door command, press to select it. This leads to the following set of dialogs: (1) First comes the Resize Text Anchor dialog. Notice that the word where you left the cursor before opening the Link menu is now hilited. This represents the default link anchor. In this case it would make more sense to hilite all of "How to Read This Book" instead of just one word, so the purpose of this dialog is to help you do that right away. The box on the left lets you extend the hilite to either side; the box on the right lets you retract it from either side. To do this with the keyboard, press to select the appropriate box, then press the or arrows to extend or retract the hilite. Using the mouse, just click on the box and then click on the appropriate arrow. When the link anchor includes the full section title, press or click on . (2) Next comes a dialog to let you confirm or change the default number assigned to the card by Orpheus. Most users will never have any need to change this. Press to move on to the next step. (3) This brings you to the Define Card dialog, which you saw earlier when the New Project procedure brought you to the Homecard. The text of the link anchor is offered as the default topic of the new card. Press when the topic is to your satisfaction. Normally you won't change any of the other options right away, except perhaps the one for "Scroll text" if you left scrolling optional in the Project Options dialog. Notice that in the "Built-in links" box, the "Origin" field contains "1-1"; this means that your new card will have an Origin link to card 1-001, where you are right now. Press to conclude this dialog. 19 (4) The last dialog lets you select an Edit window in which to load the new blank card. (Up to this point, if you cancelled one of the three preceding dialogs by pressing the entire process would be aborted. However, once you've gotten this far the new card has been created and the linking codes inserted. Cancelling this dialog merely leaves you in the current window without loading the new card.) In OH.EXE you can open up to 9 Edit windows. The dialog lists the first window, containing the Homecard, but hilites window #2 as the logical choice for loading a new card. Press to accept this. Finally you are in your new blank card. Notice that the filename at the upper right says "1-002.TES", and that the number at the left (beside the Esc:Menu prompt) indicates window #2. A little later we'll see that there is absolutely no connection between windows and cards, since any window can hold any card or other text file, and you can use any window to navigate throughout an entire project. For the moment, flesh out the new card by typing in the following two lines of text: If I've forgotten to provide special instructions for how to read this book, just press and the Reader will explain. This illustrates the most obvious approach to developing a hypertext project: typing in new text as the project grows. To save this card to disk, open the File menu and select "Save", or click on the filename on the statusbar. Importing Text In this section we'll continue expanding the Test project, showing two methods of doing so that involve importing text from external files. First we'll import an entire file in one step; then we'll load a long file in a separate window and import just a block of it. To begin, return to the window containing the Homecard. (You can do this by clicking on the window number, by pressing or , or by using the Window List dialog from the Window menu.) Move the cursor to the first letter of "What's New". We're going to make a link on this title, but this time we'll mark the link anchor before opening the Link menu. This will let us skip the Resize Text Anchor dialog. With the cursor under the "W" of "What's New", press to begin marking. Using the middle keypad, move the cursor to the right until the entire title is hilited, or click on the space just to the right of "New". (If you are using an older computer and the right arrow key just makes Orpheus say "bonk", press the NumLock key to switch out of navigation mode.) With the entire title hilited, press again to end marking. Now open the Link menu again, press to select the Door link type, and follow the dialogs as you did before. Notice that this time you don't go through the Resize Text Anchor dialog, since you've already marked your link anchor as desired. When you reach the Window dialog, 20 press to load the new card into the window suggested by Orpheus, which should be #3. We'll flesh out this card by importing an entire external text file, in this case the "UPDATE.TXT" file that came with your copy of Orpheus 2. Open the File menu and select "Import File". If your working directory is the one in which you installed Orpheus, just type in "UPDATE.TXT" and press . If the Orpheus directory is somewhere else, type in the complete path to the file or else into the file and directory and boxes until the desired filename is shown in the entry field. With the procedure completed, the entire Update file has been copied into the card in your Orpheus project. Save this card by clicking on its filename on the statusbar. Return once more to the window containing the Homecard, and make a third link on "About Orpheus". Follow the dialogs as before, and again load the new blank card into a new window, which should be #4. We'll flesh out this card by importing only a block of text copied from a much larger file, which will be loaded in another window. The file we'll use for this purpose is the manual you are now reading. Open the File menu and select "Open". If your working directory is the one in which you installed Orpheus, just type in "MANUAL.TXT" and press . If the Orpheus directory is somewhere else, type in the complete path to the file or use the file and directory boxes (pressing to move into or out of a box) to select the desired file. When you conclude this dialog, the file is loaded into the next available Edit window, which in this case should be #5. (If all 9 windows were occupied Orpheus would show you the window list to let you choose which one to use.) You should now be looking at the first page of MANUAL.TXT. Page down past the copyright line to the first paragraph describing Orpheus. We'll mark the three paragraphs so they can be copied in a block to your new card. To make this easy we'll mark the block using line mode. With the cursor anywhere on the first line of the first paragraph, press to begin marking in line mode. Use the arrow key to move the cursor down to the last line of the third paragraph. Then press again to finish marking the block. (You can also access block-operation commands through the Block menu.) For the next step, return to the window containing your new blank card, using or by clicking on the window number until you're there. To insert the marked block from the other window, press (or open the Block menu and select "Copy from window"). A dialog will open with a list of all windows containing marked blocks; since there is only one and it is already selected, press to confirm it. The marked block is now copied into your new card. Press to unmark this copy, then save this card. 21 At this point your Test project contains three cards linked to the Homecard. All four cards are in separate full-screen windows, and MANUAL.TXT is in yet another window. If you were to exit the program now, the next time you loaded the TEST project you would find yourself in the current window, with all the other windows having exactly the same contents as when you left them. (You can reload a project either from the DOS prompt, giving the project name on the command line, or by selecting "Open Project" from the Project menu.) Now, what about those links you made? Do they really give you hypertext, or do you have to switch windows all the time to jump from card to card? In the next section we'll see that the links really do work -- and that the Edit windows are only there for your convenience while authoring. Navigating Hypertext in OH.EXE To test hypertext navigation in OH.EXE, we'll start by closing all windows except the one containing the Homecard. Return to the window containing MANUAL.TXT and press to close that window. This should put you back into window #4, so press to close that one, and continue until you are back in window #1 with the Homecard. If you accidentally closed the window containing the Homecard, don't worry about it: open the Card menu and select "Home" to jump to the Homecard, and complete the jump in the current window (#1). You should now be looking at the Homecard with its three colored links to other cards. We're going to jump back and forth between each of those cards and the Homecard, first of all in window #1, then with the option of loading the target card in a new window. If you are using a mouse, it's easy: using the *left* mouse button, click on a link anchor to set the cursor on it, then click on the cursor to make the jump. Do this now on any of your three links, then retrace your steps (in this case to the Homecard) by clicking the *right* mouse button. Note that in Help and the Reader it's even simpler, since there's no cursor: you just left-click once on a link to jump through it, and right-click to return. For more about navigating with the mouse, read "Navigating Hypertext" in online Help. If you are using the keyboard, navigation is a little more complicated but more powerful in return. First, notice that all of the navigation commands are available on the Card menu, where the default accelerator keys are given as requiring the Shift key. What the menu does not show is that those accelerators are limited to the NUMBER KEYPAD, and if you are using a full-sized keyboard on a 286 or higher you do NOT have to use Shift. However, if you are using an XT (with or without a full-sized keyboard), OR if you are using certain laptop or notebook computers, you may have to turn on NumLock or add Shift as shown on the menu. In the rest of this section I'll assume that you are using a full-sized keyboard on a 286 or higher. Later on, you may wish to customize the keyboard for whatever combination of cursor control and navigational commands you find most convenient. This is done through the "Setup Orpheus" dialog on the Other menu. 22 Continuing now with the keyboard: using the middle keypad, OR the or arrows of the number keypad, move the cursor to the first link, "How to Read This Book". Now using the number keypad, press . This should jump you through the link and to the attached card, without leaving window #1. To retrace your steps, press the arrow on the number keypad. (You could also press , but the point is that retraces your hypertext jumps no matter where you are, whereas goes straight to the Homecard.) Repeat this procedure with the second and third links, just to verify the hypertext connection. Now we'll do the same thing but with the option to load the target card in another window. The purpose of this ability is to make your work easier while authoring; there is no equivalent in the Reader. To use the window facility, hold down the Control key while giving your normal navigational command. This applies whether you are using the keyboard or the mouse. After jumping to each card, give the same retrace command as you did before (right-click or the numpad arrow) *without* using the Control key. Notice that Orpheus returns to window #1 because the Homecard (your destination) is already loaded there. Repeat the procedure until all three child cards are loaded in separate windows. To find out more about navigating hypertext in Orpheus, be sure to check online Help on the topic "Navigating Hypertext". What's in a Card? Now that you have made some links (and some cards), and used them, it's time you saw what is actually in those cards that enables Orpheus to give you hypertext linking. Return to the Homecard if you are not there already. Now press . This switches Orpheus into "ascii mode", in which it displays the card's true contents. As you can see, in ascii mode your link anchors are shown with the embedded codes revealed. This is exactly what you would see if you were to load the Homecard file in any standard text editor or file viewer. If you press again Orpheus will return to "hyper mode", in which it displays your links the way your end-users will see them. Still in ascii mode, press the arrow to move the cursor to the top of the Homecard, then once more to scroll up to a line that was formerly invisible. This line is the card header, and will look something like this: OH2(TEXT,"Table of Contents") Every uncompiled card in an Orpheus project begins with a header line of a similar nature. The header tells Orpheus what type of card it is, what its topic is (if any), and so on. For further discussion of cards and the various contents of header lines, read "Hypertext Cards" in Help. (You don't need to know anything about headers to use Orpheus, as long as you are aware that they exist.) 23 If you press a few times to toggle back and forth between ascii mode and hyper mode, you may notice that besides the changing display of your text, there is one small change on the statusbar. In hyper mode, the symbol to the left of the line number is a figure 8 on its side (the infinity symbol). In ascii mode the symbol is a stack of three horizontal lines. The current mode is also indicated when you open the Edit menu. Let's take a closer look at your three link anchors in ascii mode. Unlike the card header, which you should never need to edit manually, link anchors and the other embedded codes are good things to know about. Depending on the work you do, you may never need to leave hyper mode, and if that's the case, you'll never edit a linking code manually. But it's comforting to know that should you ever need to create or edit the linking codes yourself, you CAN do so, and do it easily; and for a few advanced functions you do in fact have to. As you can see by the patterns repeated in the three sets of linking codes on your Homecard, every link anchor begins with a "<" left angle bracket, which is followed by the visible text of the link anchor. Then comes a "|" pipe symbol, followed by more codes and a final ">" right angle bracket. The "<|>" characters are the skeleton of every embedded code in Orpheus, with visible text going on the left of the "|", and the actual codes on the right. In the case of your three links, the codes all begin with a "D" (if you have followed the tutorial exactly), which represents a Door link. This is followed by a two part number -- "1-2", "1-3", and "1-4" -- which you will recognize as referring to the linked cards 1-002.TES, 1-003.TES, and 1-004.TES respectively. (In filenames the second part of the number must be padded with 0's to make three digits, as in "1-002"; but in link references and dialogs you can omit the 0's.) Although there's a lot more to linking than we can cover in a brief tutorial, there is certainly no mystery about it, nor is Orpheus particularly complicated. Read up on "Hypertext Links" in Help, check out the individual commands on the Link menu, experiment. Finishing a Project In this section we'll build a finished copy of the Test project, and see how it runs in the Orpheus Reader. Then we'll examine the virtues of incremental compilation, and try out the Simulator. With the Test project loaded in OH.EXE, open the Project menu and select "Build". (For a full explanation of everything you see, press while in this dialog.) The most important part of the Build Project dialog is the "Action" box in the lower right corner. As you can see, it lets you choose among 7 combinations of three actions: compile, verify, and assemble. We need all three steps to build a finished product, so press <4> to select "Compile->Verify->Assemble". Then press to set the builder in motion. 24 If all goes well, Orpheus will swiftly compile your cards, verify all links accessible from the Homecard, and assemble the results into a finished product named after your project: in this case, TEST.HTX. When building is completed, press a key to clear the report window. Now let's try out the Reader! Exit OH.EXE, either through the File menu or by pressing . Start up the Reader (OHREAD.EXE) with the following command at the DOS prompt (we assume that the project name is "test"): ohread test The Reader should open your project to the Homecard. Unless you have already played around with customizing your project options, the Reader will display your work using the default Reader interface and the default screen layout, which includes a simple titlebar. All of this can be extensively customized. Press to open the Reader's menu system, and explore a little. You can customize, on a project-specific basis, end-user access to features like printing, or even to the menu system as a whole. Press while in any dialog or while looking a text card (but not while in a menu). Notice that the Reader provides a series of simple Help windows for all built-in features -- but this too can be customized. Try out your links, observing how the Reader responds to keyboard and mouse input. Apart from the fact that everything is simpler (there's no distinction between the number keypad and the middle keypad, for example), you also have a choice between two sets of keyboard assignments. Actually you're seeing only a fraction of what you *could* see, because the fact is that through OH.EXE's Project Options dialog you can customize your work so thoroughly that the Reader will look as if it was programmed just for you. When you're ready, exit the Reader through the File menu or by pressing . If you have a robust file-viewer like LIST.COM, you might enjoy sneaking a peak at the contents of your finished product, TEST.HTX. What you'll see is: completely indecipherable garbage. In other words, only the Reader can read it, and no one can hack a finished version of your work. Now let's get back into OH.EXE to check out something else. Load up the Test project again, either by giving its name on the command line ("oh test"), or by using the "Open Project" command on the Project menu. We're going to see how you can test your finished work without leaving OH.EXE, and without actually building a fully finished copy. We'll do this using the Simulator (OHSIM.EXE), which you can run both as a program in its own right, or (more conveniently) from within OH.EXE. Open the Project menu and select "Simulate Reader". This tells Orpheus to fire up the Simulator; if all goes well, a message will appear reminding you of the Simulator's "emergency exit", which is . 25 (The emergency exit is there in case you intentionally disable the standard exit hotkey -- as a project option -- and forget to replace it with some other way for users to exit your work.) Once past that message you should see exactly what you saw in the Reader. However, if you try to open the menus you'll discover that the Simulator doesn't have any, because it isn't a full copy of the Reader. The Simulator has to do certain things that the Reader does not, so in order to keep the program a reasonable size any unnecessary parts have been left out. Unlike the Reader, which uses a *fully assembled* copy of your work, the Simulator only uses the compiled (but not assembled) portions of it, which reside in your project's "CMP" files. CMP files are generated during the compile stage of the build process; there is one in each storage directory, to hold compiled versions of all of the cards in that directory. The assembly stage puts together your finished work by copying these compiled parts found in the CMP files. Let's demonstrate further the difference between Reader and Simulator. If you are still in the Simulator, press to exit it. With your project loaded in OH.EXE, type a line or so of text in whatever card you happen to be in, and save that card. Now open the Project menu and select "Compile, Simulate". This tells Orpheus to look for any cards that have changed or been added since the last compilation, compile them, and then open the Simulator. When the process is complete you will again be in the Simulator, looking at the compiled card with the new text that you just typed in. However, if you were to exit the Simulator and OH.EXE and then load up your project in the Reader as we did earlier, you would find that the Reader displays the old version of the card, because the HTX has not changed. To update the HTX, open the Build dialog and choose any action that includes the assembly stage. Though the Edit windows of OH.EXE give you a pretty good view of what your work will look like in the Reader, the Simulator takes you one step closer to the goal without the extra processing required to build the final product. Besides this purpose, the Simulator is also used for testing scripts and adding hotspots to graphics. Summing up: for a real project, you would devote a certain amount of time to tuning your project options and customizing the appearance and functionality of the Reader interface. This and many related topics are covered extensively in online Help: on the Help Contents page, select "Finishing a Project" and explore. Over time you will dig into Help on various topics encountered in the Project Options, Build Project, and other dialogs, but some of the topics reached through "Finishing a Project" touch on wider considerations, such as distributing your work to end-users. 26