Programmer 7500

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

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / ORPH153B.ZIP / MANUAL1.DOC < prev next >

Wrap

Text File | 1993-03-14 | 159.0 KB | 3,541 lines

ORPHEUS An Integrated Authoring System For Hypertext Writers - User's Guide - * Part I * Copyright 1993 Hyperion Softword Orpheus is two programs: the Orpheus Author (OH.EXE), a program for creating electronic books and online documentation; and the Orpheus Reader (OHREAD.EXE), a program for end-users, to be distributed with such works in their compiled form. 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 authoring program for up to 30 days. If you wish to use the system after that period you must pay the registration fee of $49. For more information see Chapter 7, or print and fill out the REGISTER.DOC file and send it with your payment to: Hyperion Softword 535 Duvernay Sherbrooke, QC Canada J1L 1Y8 819-566-6296 (voice) 1 ACKNOWLEDGEMENTS: Special thanks to: - Daniel Coulombe, SYSOP of Synapse BBS, the official Home of Orpheus! (See the README file for phone numbers.) - Lynn Hildre of Alaska EPAC, for her dedication to excellence and unerring ability to find bugs in the woodwork. Orpheus Author 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, <F1> means press and release the F1 key, <H> means press and release the "h" key. Combination keystrokes are hyphenated; for example, <Alt-F> means press and hold down the Alt key, then press the "f" key, then release both keys. The term "Orpheus" is generally used in reference to OH.EXE, the authoring program which is the heart of the Orpheus system. Occasionally it refers to the system as a whole, which includes OHREAD.EXE and both programs' help and utility files. 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 ......................................... 5 Quickstart ......................................................... 5 How To Use This Manual ............................................. 5 System Requirements ................................................ 6 Installation ....................................................... 6 Getting Help ....................................................... 6 Is Orpheus For You? ................................................ 7 Chapter 2 - The Orpheus Environment ................................. 9 Windows ............................................................ 9 Workspace .......................................................... 9 Statusbar .......................................................... 10 Using Menus ........................................................ 12 Using Help ......................................................... 13 Mouse Interface .................................................... 13 Chapter 3 - Tutorial : Making Hypertext ............................. 16 Starting With a Homecard ........................................... 16 What's Going To Happen ............................................. 17 Opening Some Doors ................................................. 18 Is Your Data Safe? ................................................. 19 Navigating Hypertext ............................................... 19 Windows & Navigation ............................................... 20 Windows & Editing .................................................. 20 One Step "More" .................................................... 21 Behind The Scenes .................................................. 22 When We Return ..................................................... 23 Chapter 4 - Tutorial : Flexible Hypertext ........................... 25 Importing Text ..................................................... 25 Moving Links ....................................................... 27 Splitting .......................................................... 28 Designating Home ................................................... 28 Crosslinks & Retrace ............................................... 29 Resizing Linkwords ................................................. 31 Changing Link Types ................................................ 32 Unlinking .......................................................... 33 Recovering ......................................................... 33 Chapter 5 - Tutorial : Completing a Project ......................... 35 Sweating The Details ............................................... 35 Copyright ...................................................... 35 Cardlength ..................................................... 36 Full Title ..................................................... 36 Include Notes .................................................. 36 Your Colors .................................................... 36 3 Graphic Titlebar ............................................... 37 Check the "More" Corner ........................................ 37 Check the Frame ................................................ 37 "Check Card" Command ........................................... 37 Check Linkwords ................................................ 38 Use Tour Mode .................................................. 38 Compiling Your Project ............................................. 39 Distributing Your Work ............................................. 40 The Orpheus Reader ................................................. 43 Cleaning Up ........................................................ 44 Chapter 6 - Shareware : Registering Orpheus ......................... 45 Licence ............................................................ 45 What You Get When You Register ..................................... 45 Site Licencing ..................................................... 46 Sharing Orpheus .................................................... 47 A Note to Pioneers ................................................. 47 Chapter 7 - Orpheus Utilities ....................................... 48 REGIT.EXE .......................................................... 48 SNAPSHOT.EXE ....................................................... 50 Appendix A - Orpheus and Other Software ............................. 52 Disk Caches ........................................................ 52 Desqview ........................................................... 52 Appendix B - Using Orpheus on a Network ............................. 53 Appendix C - Using the "ORPHEUS" Environment Variable ............... 54 Appendix D - Format of An Uncompiled Card ........................... 55 Structure of a Card ................................................ 55 Number Systems ..................................................... 55 The Filename ....................................................... 56 Header and Link Codes .............................................. 57 The Header ......................................................... 58 Linkwords .......................................................... 59 4 --------------------------------------------------------------------------- CHAPTER 1 - GETTING STARTED --------------------------------------------------------------------------- Topics in this chapter: Quickstart How To Use This Manual System Requirements Installation Getting Help Is Orpheus For You? 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 <F1>. To make sure you get off on the right foot, I would strongly suggest you read Chapter 3, the tutorial on making hypertext the Orpheus way. How To Use This Manual This manual is a supplement to the online Help in Orpheus Author (OH.EXE). Use it to find out what Orpheus is all about, to get set up, to take your first few steps on the path of hypertext authoring. Bear in mind however that the most detailed information on Orpheus is in the program itself, in online Help, which you can open at any time by pressing <F1>. With the exception of information on programming hypertext, this manual tells you only a fraction of what you will learn through the Help system. (See Part II, MANUAL2.DOC, for information on programming.) To print out this manual, set your printer to 6 lines per inch, 10 characters per inch, and use the following command at the DOS prompt: COPY MANUAL1.DOC PRN Then do the same with MANUAL2.DOC. Alternately you can load the files into your favorite word processor and print them from there. There are 59 lines per page, with the last line of text at line 55. An alternative to printing out the manual is to read it in a special Orpheus window called FileView. To do this, start the authoring program by giving the "OH" command at the DOS prompt. Press <Alt-V> to switch to the FileView window, and type in the name of this manual, "MANUAL1.DOC". Then press <Enter>. Once the file is loaded, you can switch back and forth between FileView and the current Edit window by pressing <Alt-V>. 5 System Requirements Orpheus Author (OH.EXE) requires 480K of RAM, DOS 3.2 or higher, and a hard disk. You do not need a graphics display card unless you wish to link graphics into your work. The Orpheus Reader (OHREAD.EXE) requires 256K of RAM and DOS 3.2 or higher; a hard disk is NOT required. A graphics display card is only needed to view whatever graphics (if any) may be included in a work. Both programs should run on any XT- or AT-compatible computer. Both support the use of a Microsoft-compatible mouse, but a mouse is not required except in OH.EXE, and only for making hotspots in graphics or ansi screens. Installation Orpheus should be installed in its own subdirectory on your hard disk. An example would be "C:\ORPHEUS", but the name of the subdirectory is up to you. Copy all of the files on your distribution disks into this subdirectory. Orpheus requires that the DOS "Files" variable be set to at least 15. 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 don't have a CONFIG.SYS file you will need to create one; consult your DOS manual, or type in the following lines at the DOS prompt (leaving out the comments at the right, which begin with ";"): c: ; If in another drive. cd\ ; copy con config.sys ; Tells DOS to create CONFIG.SYS file. FILES=15 ; Our setting. ^Z ; DON'T TYPE THIS! Instead, press ; the F6 key, which inserts "^Z", ; then press <Enter>. If you have changed or created your CONFIG.SYS file you must now reboot the computer for the new setting to take effect. Getting Help If you get stuck or need something explained, the FIRST thing to do is to explore online Help. In just about all situations, pressing <F1> calls up context-sensitive Help with an explanation of exactly what you need to do or to know. Every item on every menu has a Help text which you can access by clicking on the item with the right mouse button, or by moving the selection bar to it and pressing <F1>. The main menu in Help gives you access to every topic connected with the program. 6 If you're still stuck, the SECOND thing to do is to read this manual, assuming that you need a tutorial or more information on programming. If you're still stuck after that, or if you have encountered a bug or run into other difficulties, please DO contact me (Rod Willmot) at Hyperion Softword. There are three ways to reach me: by voice, by modem, and by mail. (1) Call 1-819-566-6296, anytime between 11:30 a.m. and 11:30 p.m., Eastern Time (generally 7 days a week). I can help best if your computer is up and running with Orpheus loaded. (2) If you have a modem there are several ways you can reach me, as detailed in the README file included with the shareware version, or on the "Orpheus Support" sheet if you are a registered user. This method is inexpensive and relatively fast, with the turnaround time being 24 hours in some cases, a few days at most. (3) Write to me at Hyperion Softword, 535 Duvernay, Sherbrooke, QC, Canada J1L 1Y8. This is a good way to discuss ideas you may have; it is *not* a good way to get help because the turnaround time for me to hear from you and reply is simply too long. Is Orpheus For You? What do you, as a hypertext writer, care about most? Do you want your reader to connect with your work -- to find it attractive, easy to access, rewarding to use? Do you want to compose spontaneously in hypertext, to follow your inspiration without having to worry about filenames and codes? Do you want to transform conventional text into something truly different -- a place where the reader can move at will, swiftly and easily finding whatever he needs? Do you see the computer screen as a whole new medium of communication, one as different from the printed page as books from the spoken word? If any or all of the above are true, Orpheus is for you. The kind of person Orpheus is NOT for is the one who is determined to use the computer as nothing but a glorified typewriter. Contentedly captive in the Age of Print, this person sees the computer screen as a shrunken viewport on a would-be page. When he thinks of publishing he thinks of paper. When he thinks of hypertext he thinks of scattered files that he would like to link together, harum-scarum, like newspaper columns recycled into a book. In Orpheus, the unit of communication is the screen, and the unit of composition is the hypertext card, which in compiled form is the size of the screen. From the reader's point of view, this means that instead of opening files and scrolling through them from beginning to end, you move from screen to screen through a hypertext network. From the author's point of view, it means that for the most part you never even think about files: you extend your growing document by opening "doors", which Orpheus automatically links to new cards. You can navigate effortlessly through a vast work in progress, using simple directional keystrokes on the number keypad, or by pointing and clicking with the mouse. Most hypertext systems remain true to the conventions of printed text, which we can sum up in one word: linearity. An example of linearity is 7 the idea that a story should be told along a straight line from beginning to end. Occasionally, it's true, a certain linear extension is appropriate to part of a story or exposition. Usually however, linearity is just a habit, a result of centuries of conditioning by the physical obligation to put one thing after another: spoken words strung out on the thread of Time... calligraphy on a rarely-opened scroll... pages typed, retyped, and printed, sewn into their sole correct order in a heavy tome. Hypertext dissolves that conditioning, letting your words and ideas blossom into their natural multiple dimensions: instead of a string, a galaxy; instead of a scroll, a palace of countless interconnecting rooms and halls; instead of a tome of tedious chapters, a garden that unfolds in all directions. It comes down to this: other hypertext systems *expect* you to scroll, because they deal in files; Orpheus eliminates scrolling from the equation. Here's where some writers get hot under the collar. Yes, it does take a little more work to write well for the screen, to express your ideas and information in chunks of 24 or 25 lines. But think about your reader: with scrolling hypertext, he never knows if an important keyword is just offscreen. He loses track of where he's been, can't recall whether such-and-such a topic was in the current file (scrolled out of sight) or in another link. With non-scrolling hypertext, the reader sees at a glance what paths there are to take, can explore and return and explore again, swiftly and easily, without ever getting lost. Additionally, the visual orientation of non-scrolling hypertext encourages you, the author, to design more readable screens. It encourages you to express yourself more succinctly -- to notice the repetitions and verbosity, trim them, and put punch into your writing. Naturally, sometimes you do want several paragraphs to follow each other in a straight line, and as a matter of fact Orpheus lets you accomplish that quite handily. Using the "More" link type (created through the Split command on the Link Menu), you can connect as many linear elements as you wish. The effect is like a simple <PgDn> -- you just flip down a screenful at a time instead of scrolling. Is Orpheus for you? Are you wondering whether you'll be able to write in screen-sized chunks? Keep in mind that Orpheus does everything possible to make hypertext writing easy. First, throughout the authoring phase every card has a 50-line workspace, which you *can* scroll. Second, Orpheus lets you do everything within OH.EXE's Integrated Development Environment. If you wish, you can also do some or all of your writing in your favorite word processor, importing your text into Orpheus through the FileView window. (If you choose to do this, just remember to save a copy of your text in non-document mode -- as plain ASCII text -- before importing that copy into Orpheus.) 8 --------------------------------------------------------------------------- CHAPTER 2 - THE ORPHEUS ENVIRONMENT --------------------------------------------------------------------------- Topics in this chapter: Windows Workspace Statusbar Using Menus Using Help Mouse Interface Orpheus Author is the first Integrated Development Environment for creating hypertext documents. Everything you need to compose, modify, and enhance your hypertext is right at your fingertips. Best of all, this environment lets you see your work exactly as your readers will see it when you compile and distribute it with the Orpheus Reader. Windows Orpheus provides four Edit windows, plus a fifth window called FileView for reading and importing external text files. The Edit windows are for writing hypertext and for navigating through your work in progress. Each Edit window has a 50-line workspace -- the number of lines in an uncompiled hypertext card. Normally the Edit windows are loaded with cards from different branches of your project; this lets you keep tabs on up to four different "growing points" of your work. Orpheus saves your window configuration when you quit the program; the next time you load that project, each Edit window will have the same contents as when you exited. For more on Windows in Orpheus, check out the Window Menu and read online Help. Workspace When you start up Orpheus the first time, what you see is a mostly blank screen with the Orpheus Statusbar on the top line. Actually, you are looking at an empty hypertext card. Like an index card, a card in Orpheus has a certain height and width; it does not go on forever. If you press the <Down> arrow and keep your eye on the line counter (towards the right of the Statusbar), you'll notice that the cursor goes as far as line 50. This is your workspace in every card in Orpheus: 50 lines, the width of the screen. However, although your workspace is 50 lines per card, the eventual length of your cards in compiled form will be either 24 or 25 lines, depending on whether or not you want your finished work to be presented with a Titlebar. Why so few? Orpheus takes a screen-oriented approach 9 to hypertext: instead of stringing together long text files and making the reader scroll through them, Orpheus encourages you to develop true electronic documents in which the reader moves from screen to screen, with the openings to new paths always clearly visible. From the moment you begin writing in Orpheus, think about what you want your readers to see: not just what you want to say to them, but the visual impressions you want them to have as they move through your work. Like a well-designed book, a carefully-prepared network of hypertext cards conveys information much more effectively, and is certainly more pleasant to read, than a presentation that merely fills the screen with unformatted text. Use the lower half of your workspace for the "overflow" as you develop your text. If the overflow becomes suitable for a card of its own, open the Link Menu and select "Split" to create a new card for it. Statusbar A variety of messages and symbols appear on the Statusbar to 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. Through the Options Menu you can set the Statusbar to appear on either the top or bottom line of the screen. The illustration below represents all of the items that might appear: Esc:Menu |1 2 3 4 V| Push Marking =Bookname= Init More iwS [32] * | < | U | > 1 2 3 4 5 6 7 8 9 10 11 12 (1) Reading from left to right, the first item reminds you how to open the menu system. Note that you can open the menus even faster using the Alt key in combination with the first letter of the menu's name; for example, <Alt-L> opens the menu system and pulls down the Link Menu. You can also open the menu system by clicking on "Esc:Menu" with the left mouse button. (2) Next is the list of windows, "1 2 3 4 V". Windows 1 to 4 are Edit Windows, for writing hypertext; window V is the FileView window, for read-only access to external text files. The fast way to switch to any particular window is to use the Alt key in combination with the window name; for example, <Alt-2> switches to window 2, while <Alt-V> switches to the FileView window. <Ctrl-V> switches you between the current Edit window and the last one used. See the Window Menu for more information. (3) Indicating your current editing mode, "Push" is for Pushright (new text pushes text at the cursor to the right), "Over" for Overwrite (new text overwrites text at the cursor). To switch from one mode to the other, open the Options Menu or press <F10>. (4) Next comes a message area that is normally blank. The illustration displays the "Marking" message, which would appear if you were marking a block of text. When you mark a block in one window and then switch to 10 another window, the message area says "Import" to remind you that using the Paste Command (from the Edit Menu) will import the marked block into the current window. When marking in line mode the message is capitalized; in column mode the message is followed by the letter "C". (5) This is the filename of your Homecard, which Orpheus uses as the short name for your book. When you are actually in the Homecard the name is capitalized and in quotation marks: "BOOKNAME"; when you are in other card you see it in the form illustrated, ≡Bookname≡. Though the name of the Homecard is limited to 8 letters without an extension, Orpheus provides an area for you to enter a proper title of up to 32 characters; this will appear on the titlebar of the Orpheus Reader when your work is compiled. (Select "Full Title" on the Project Menu.) (6) The "Init" flag appears when the current card has an Init link. An Init is a link to a special card containing only programming commands instead of text for display. The Orpheus Reader detects and processes Inits automatically. To jump to an Init within OH.EXE, click on the flag with the left mouse button, or open the Link Menu and select "Edit Init". (7) The "More" flag appears when the current card has a More link. This is a hypertext link much like a Door or Note, but attached to the card as a whole rather than to a linkword. A More link is a link to the "next" card; it's a way of saying, "Select me to see what comes right after the last line on this card." When your work is compiled and displayed in the Orpheus Reader, More links are shown by the symbol "=More=" appearing in the lower right corner of the screen; the user can select or click on this as he would a linkword. (Why does the "More" flag appear on the statusbar in OH.EXE, rather than in the lower right corner where it belongs? To keep it out of the way while you're editing.) (8) The "iws" cluster signals the state of three edit modes: AutoInsert, Wordwrap/AutoReformat, and AutoSave. When an option is off its letter appears in lowercase; when on, in uppercase. The middle symbol is a bit special, however: as you would expect, it's a "w" when Wordwrap is turned off, a "W" when it is turned on; but when AutoReformat is selected it's an "R", except when you are in a card that you have "Locked" to prevent accidental formatting -- in which case it's a bright "L". All of these options are set through the Options Menu. (9) Square brackets on either side of the line number indicate that you have set a temporary left or right margin. Pressing <Ctrl-[> sets a temporary left margin at the cursor position; the same keystroke cancels the tempory margin. (10) Indicates the line on which the cursor is positioned, from 1 to 50. (11) A bright "*" appears when the current card has changed since you last saved it to disk. Press <F2> to save, and it disappears. (12) The right of the statusbar is occupied by a trio of navigational commands for use with the mouse. The illustration represents them as 11 "<", "U", and ">", since the symbols used onscreen wouldn't come out on your printer. Using the left mouse button, clicking on the command at the left jumps you to the Homecard; clicking on the command at the right jumps you to the parent of the current card; and clicking on the command in the middle jumps you to the previous card visited, letting you retrace up to 50 moves in any direction. I mentioned earlier that Orpheus lets you choose between a cardlength of 24 or 25 lines, as it will appear when your work is compiled and displayed in the Orpheus Reader. (The default cardlength is 24 lines; to change this, open the Project Menu and select "Cardlength".) Since the standard screen has 25 lines, 24-line cards leave room for the Orpheus Reader's Titlebar, while 25-line cards do not. When the Reader detects a book that uses 25-line cards, it automatically displays a message telling the user how to pop up the Titlebar and open the menu system; it then gives over the entire screen to your hypertext cards. In OH.EXE the statusbar is always displayed regardless of cardlength, so there is a special command to let you view a 25-line card as it would appear in the Reader. <Alt-C>, the "Check Card" command on the Tools Menu, also shows other details such as the true location of the =More= flag. Using Menus Orpheus Author 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 <F1>, or click on it with the right mouse button. Pressing <Esc> opens the menu system and automatically pulls down the File Menu or the last menu opened. Once you are familiar with Orpheus you'll skip that step and pull down exactly the menu you want using the Alt-key method. For example, <Alt-F> opens the File Menu, and <Alt-L> opens the Link Menu. The only exception is when you are in the FileView window, where <Esc> is required to open the special FileView 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 <Enter>. Alternately, just press that item's hilited letter, or click on it with the left mouse button. Some menu items lead to submenus; for example, on the File Menu selecting "Print" leads to a submenu of print-related actions, including "Set Print Options", which leads to a further submenu. Many menu items allow you to set options or even enter text. Notice that some option-type items use square brackets [] while others use parentheses (). When square brackets are used it means that you can select that option in combination with other options; when parentheses are used it means that 12 selecting one option turns off another option. For example, on the first Print submenu parentheses are used for the mutually exclusive options of printing to the printer or to a disk file. On the second Print submenu square brackets are used for the various dimensions you may want to set, such as margins. With a submenu open, press <Esc> to back up to the previous menu level. With no submenu open, <Esc> closes the menu system. See the topic on "Using the Mouse" in online Help. While the menu system makes Orpheus easy to learn, keyboard accelerators let you bypass the menu as you quickly become an expert. Practically all accelerators are indicated on the menus, with the remainder (for cursor control and so on) listed in online Help under topics linked to "Using the Keyboard". 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 <F1> or even just <H> (dialogs only). You can also return to the previous help-topic by pressing <Alt-F1>. For example, suppose you want to draw a diagram using the Boxdraw feature, and aren't quite sure which keys to use. Open the Tools Menu and select Boxdraw, then press <F1> for help. When you've learned enough to begin drawing, press <Esc> to close Help. Now at any time while drawing you can press <Alt-F1> and Help will return with the precise instructions you were last looking at. Many Help topics include hypertext links connected to other topics. The presence of such a link is indicated by a hilited word or phrase, or one that already has the selection bar on it. Use the arrow keys to move the selection bar to other linkwords; press <Enter> to jump to the selected link. The up/down arrows keys also scroll the text, or you can page through a topic with PgUp/PgDn. Press <Home> or <End> to jump to the beginning or end of a topic. Finally, note that although the Orpheus Reader is much simpler and easier to use than Orpheus Author, it uses the same Help system, but with different texts. Mouse Interface When you begin an Orpheus session the mouse pointer is set on the far left of the Statusbar. In Edit windows the mouse pointer disappears automatically when you start typing, but reappears if you move the mouse. WINDOWS Click the left button on one of the symbols from the "1 2 3 4 V" cluster on the Statusbar. Numbers 1 to 4 are for the Edit windows, while V is for the FileView window. 13 MENUS To open the menu system, click the left button on the words "Esc:Menu" on the statusbar. Click the left button on a menu item to select it; click on the selected item to activate it -- like pressing <Enter>. For context-sensitive Help, click the *right* button on any menu item. To close the current menu, click either button outside the borders of the menu. DIALOGS Most dialogs include command buttons enclosed in angle brackets, such as < Help > or < Cancel >. Click the left button on any such command to perform it. Many dialogs also include commands on their window border; for example, the Help window displays " Help Exit Back " on its border; you can click on any border command just as you would a command in angle brackets. Click the right button to close a dialog, or click on "Exit". LISTS AND SCROLLABLE TEXT To scroll text in the Help window, or to see the rest of a file list, click or hold down the left button on either the top or bottom border of the window. CURSOR CONTROL While editing, click the left button anywhere in the text area to place the cursor there (unless there is a marked block -- see below). NAVIGATING HYPERTEXT Click the left button on a linkword to set the cursor there, then click again to jump through the link. If the card has an Init or More link, click on the prompt on the Statusbar to jump to the linked card. Return from jumps by clicking on the command symbols on the right of the Statusbar: on "<" to jump to the Homecard, on "U" to retrace your steps in all directions, on ">" to jump to the parent of the current card. BLOCK OPERATIONS There are three marking modes (stream, line, column), all of which you can use while marking with the mouse. There are also three actions (move, copy, frame) which you can perform with a single mouse-click instead of through the menus. The right button is for marking/unmarking, the left button for actions. To determine the current mark-mode and block-action, slip the mouse pointer into the message area on the statusbar (this is a normally blank space to the left of the title). You will see the prompt "(Strm - Move)". This means that marking with the mouse would occur in stream mode, and that clicking the left button with a block marked would move the block to the location of the pointer. Click on the left side of the dash to rotate through stream, line, and column modes. Click on the right side to rotate through move, copy, and frame actions. To close this mini-dialog, move the pointer off the statusbar. To mark a block, move the mouse pointer to the beginning of the area to mark, then press and hold down the right button and drag the pointer to the end of the area to mark. Marking is in the current mark-mode as explained above. To complete the mark, release the right button. To 14 unmark a block, *click* the right mouse button. When a block is marked, clicking the *left* button performs the current action as described above. If the action is move or copy, the result takes place at the location of the mouse pointer. If the action is frame, it takes place at the marked block. Framing is ONLY performed if the block was marked in column mode; moreover, if the current mode is column and the current action is frame, the Frame Dialog pops up automatically when marking is completed. FILEVIEW The FileView window places all of its commands on a command bar at the bottom of the screen. You can click the left button on these commands or press the indicated key. "AutoMark" marks all 23 lines of visible text; "Search" opens the Search Dialog; "Open" lets you load a new file; "Close" ends the FileView session, closing the file and releasing memory; "Top" and "End" jump to the beginning or end of the file. The large up/down pointers scroll by 23-line chunks (like pressing PgUp/PgDn), while the arrow pointers scroll by line after moving the cursor (like pressing Up/Down). Finally, "Return" switches you back to the current Edit window while leaving FileView open. BLOCK OPERATIONS IN FILEVIEW To mark a block: with the mouse pointer on the line at which you wish to begin the block, press and hold down the right mouse button; move the pointer to the line ending the block; then release the button. Click on "Return" to switch back to the current Edit window, then move the pointer to the line where you wish to insert the block and click the left button. (For more information, press <F1> while in FileView and select "Mark/Unmark".) If you are importing a long text as a series of More links, AutoMark/AutoMORE is the speediest method. When a block has been AutoMarked, you can use AutoMORE to append a More link to the card in the current Edit window and automatically copy the marked block to the new blank card. Before using this technique, make sure that the card in the current Edit window is the one you wish to use for this. Back in FileView select "AutoMark" to mark all 23 visible lines. You can resize the block with the up/down arrows (to reduce it) and the large up/down pointers (to restore part that was reduced). Notice that the "AutoMark" has become "AutoMORE"; click on the command now, and Orpheus adds a More link to the current card and copies the marked block into the newly created card. EDIT MODES You can toggle edit modes by clicking on the associated prompt or symbol on the Statusbar. For example, to switch from Pushright to Overwrite mode, click on the "Push" or "Over" flag on the Statusbar. Three other modes -- AutoInsert, Wordwrap/ AutoReformat, and AutoSave -- are indicated in the "IWS" cluster to the right of the title area, and you can toggle them with a mouse-click too. SEARCH/REPLACE When doing a "Replace All (Confirm Each)" operation, click the left button on the found text to replace it, or anywhere else to skip that instance. Click the right button to cancel the operation. 15 --------------------------------------------------------------------------- CHAPTER 3 - TUTORIAL : MAKING HYPERTEXT --------------------------------------------------------------------------- Topics in this chapter: Starting With a Homecard What's Going To Happen Opening Some Doors Is Your Data Safe? Navigating Hypertext Windows & Navigation Windows & Editing One Step "More" Behind The Scenes When We Return... In this chapter we'll do a practice run at making hypertext in Orpheus. You'll find out how to open links, how Orpheus keeps your book together, and how it uses multiple Edit windows to give you four-point access to your work. At the end of the chapter we'll leave the results intact so that you can expand on them in the next tutorial. Starting With a Homecard We'll assume that you have installed Orpheus as described in Chapter 1, in a directory of its own on your hard drive, and that now you are in that directory looking at the DOS prompt. To start, type the command below at the DOS prompt, then press <Enter>: OH TEST When Orpheus loads you'll see the title "Test" in the middle of the statusbar, with the rest of the screen being an empty card. After we type in a few words and open our first link, this card will become a Homecard, the starting point for an electronic book. Every book made in Orpheus has one Homecard, which resides as a file in your working directory. Homecards are the only files whose names you create yourself. When you start making links, Orpheus creates the linked cards for you, naming them automatically and storing them in a subdirectory named after the Homecard. We won't be doing anything fancy in this practice run, so let's identify the Homecard so that you'll be sure to recognize it later on. Press <Enter> a few times to bring the cursor down, then type: ** THIS IS THE HOMECARD ** ...and here is door1 in it. 16 What's Going To Happen Orpheus can be disconcerting at first if you're used to more traditional software, so I'd like to sketch out what's going to happen as we start making links. In Step 1, we'll have a Homecard in window 1, with the other three Edit windows empty: STEP 1 Window 1 Window 2 Window 3 Window 4 ====== +======+ empty empty empty | Home | +======+ In Step 2, we'll leave the Homecard in window 1, and will find ourselves in window 2 with the first "child card". Since these are full-screen windows you may think that your Homecard has vanished, but it hasn't. Not only is it waiting for you in window 1, you could easily *navigate* to it from the card in window 2. (We'll get to navigation later.) STEP 2 Window 1 Window 2 Window 3 Window 4 ====== |Up +======+ +====+===+ empty empty | Home | | Child1 | +===+==+ +========+ |Dn In Step 3, we'll leave the first child card in window 2, and will go to window 3 to make the second child card. As the diagram shows, the Homecard in window 1 is "downlinked" to something, the card in window 2 is "uplinked" to something and "downlinked" to something else, and the card in window 3 is "uplinked" to something. STEP 3 Window 1 Window 2 Window 3 Window 4 ====== |Up |Up +======+ +====+===+ +====+===+ empty | Home | | Child1 | | Child2 | +===+==+ +====+===+ +========+ |Dn |Dn Finally, in Step 4 we'll end up in window 4 to make yet another card. Trust me, you won't be losing data -- the other cards will really be safe in the other windows, AND you will always have access to each and every one of them in whichever window you happen to be using. STEP 4 Window 1 Window 2 Window 3 Window 4 ====== |Up |Up |Up +======+ +====+===+ +====+===+ +====+===+ | Home | | Child1 | | Child2 | | Child3 | +===+==+ +====+===+ +====+===+ +========+ |Dn |Dn |Dn 17 As you'll see, the Edit windows give you four different viewports on your electronic book. This doesn't mean much when your book is just a handful of cards; but when it grows into a complex hypertext network of dozens, hundreds, even thousands of linked cards and graphics, you'll appreciate the ability to have widely separated areas instantly available. Opening Some Doors All right, you're in the Homecard and have typed the lines below: ** THIS IS THE HOMECARD ** ...and here is door1 in it. Place the cursor on "door1" and press <Alt-L> to pull down the Link Menu. Press <Enter> to select "Door", meaning a Door link. The word "door1" will change color and a dialog will pop up; this dialog gives you the opportunity to "resize" the linkword, meaning to extend the colored part left or right, or to retract it. For now we'll stick to the basics, so just press <Enter> to accept the default size for this linkword. Next a second dialog pops up, which we'll call the "Jump now?" dialog. Again, just press <Enter> to accept the default choice, which is to jump to the newly created linked card in window 2. Was that too fast? (That's the way it should be.) Look at the diagrams above, and check out the statusbar: in the "1 2 3 4 V" cluster the number 2 is hilited, meaning that we are now in window 2. Though you can't see it just now, the Homecard you made is really a Homecard with a link in it, and we have proceeded to Step 2: the blank card we're looking at is a child card linked to the Homecard. Type in the following to identify it: This is Child Card 1, directly linked to the Homecard. ... and here is door2, the second linkword. To carry on to Step 3, place the cursor on "door2" and do exactly as you did above: press <Alt-L> to open the Link Menu, press <Enter> to select "Door", press <Enter> to accept the default linkword size, and press <Enter> again to accept the default jump choice (to window 3). Now we're in window 3, and once again you may be worrying that you've lost your data. But you haven't. Type in the following: This is the second Child Card, and it comes from Child Card 1. ... and here is door3, the third linkword. 18 To carry on to Step 4, place the cursor on "door3", press <Alt-L> to open the Link Menu, and press <Enter> three times to accept the default choices. Finally, type in the following on the new blank card: Believe it or not, this is the third Child Card! Is Your Data Safe? Time to check up on Orpheus. I've assured you that your Homecard and the other cards you created are still in their original windows, but now you're going to see for yourself. Press <Alt-1> to switch to window 1: there is your Homecard. Press <Alt-2> to switch to window 2: there is Child 1. Press <Alt-3> to see window 3, and finally <Alt-4> to return to window 4. It's all there. This is the way to start every new project in Orpheus: let your windows fill up, then switch to one where you want to continue working. Each time you open a new link you'll be able to choose where to put the newly-created card for it: when you press <Enter> in the "Jump now?" dialog you accept the choice made by Orpheus, but to select a different window number you simply press that number or click on it with the mouse. Navigating Hypertext At this point you should be in window 4, as shown in the "1 2 3 4 V" cluster on the statusbar. And you should be looking at your "Believe it or not" card, child 3. Now we're going to navigate WITHIN window 4 to demonstrate that the hypertext cards you've made are truly linked together. To keep things simple we'll just use the keyboard, but later you'll learn to navigate with the mouse as well. *** IMPORTANT *** Keyboard navigation in OH.EXE is accomplished using the number keypad. If you have an 84-key keyboard or an XT-class computer, you must turn on NumLock in order to navigate; otherwise you'll simply move the cursor. Place your hand on the number keypad (with NumLock ON if necessary) and press <PgUp>. Now instead of looking at the third child card, you're looking at its parent -- child 2. Press <PgUp> again, and you're looking at child 1. Press <PgUp> once again and you're looking at the parent of them all, the Homecard. Now let's navigate downwards. You should be looking at the Homecard. Check the cursor position: if it is not on the linkword "door1", press the <Down> arrow on the number keypad to move it there. Now press <PgDn>, and you will jump to the first child card. Press <Down> again to put the cursor on the linkword "door2", and again press <PgDn>. Continue this way until you're back in the last child card. 19 Sum up for a moment what you've learned so far: <PgUp> jumps you to a card's parent; <Down> moves the cursor to a linkword, as does <Up>; and <PgDn> jumps you to the card that is joined to the linkword at the cursor. Again, navigation is done only on the number keypad, with NumLock ON if you have an XT-class computer. To do things like scrolling or moving the cursor in the normal fashion, use the middle keypad or, if you have an XT-class computer, turn NumLock off. Before trying some bigger jumps, let's set a bookmark at the current location, which should still be the last child card. Using the number keypad's End key, press <Ctrl-End> . A message will appear for a second or two, saying "Bookmark set". Now press <Home>, and as you might expect this jumps you to the Homecard. To return to where you were before, you _could_ navigate down card by card, but since you've set a bookmark there's an easier way: press <End> on the number keypad, and there you are, back in the last child card. Windows & Navigation Each of the four Edit windows gives you the same navigational freedom as you have just experienced in window 4. To prove this, press <Alt-1> to switch to window 1, where your Homecard should be waiting. Now try the same navigational moves: <Down> to move the cursor to the linkword, <PgDn> to jump through it, <PgUp> to return to the parent, and <Home> to jump to the Homecard. Notice however that if you press <End> nothing happens; this is because each window has its own bookmark, and you haven't yet set a bookmark in window 1. Experiment some more by switching to the other Edit windows and navigating up and down. At the moment, with just 4 cards in this miniature book, the ability to have 4 separate viewports on your work may not seem too important. But wait till you get deeply involved in a real book, with multiple branches and sub-branches. It's like being a world traveller with houses in Rome, Paris, New York, and Singapore -- or rather, with ONE house whose four doors open onto whatever parts of the world you take them to. Windows & Editing By now you may have noticed that you could easily end up with all four Edit windows holding the same card. I'd like you to do this now: switch to each window in turn and press <Home> to load it with the Homecard. What exactly is happening here? How many copies of that card ARE there? Does Orpheus hold 4 complete copies of the entire book in memory, one in each window? To answer the last question first: no, Orpheus doesn't need to hold the entire book in memory, because every card contains the embedded data linking it to the rest of the book. Each window holds just one card at a time. As for how many copies of a card there may be, in MEMORY there can be up to 4, but on DISK there is only one. 20 Let's demonstrate this with an experiment. I'll assume that as instructed above, you've loaded the Homecard in all four Edit windows. Switch now to window 2 if you're not there already, and type a few words, anything you please. Now switch to window 3 and type something different. Do this again in window 4, again typing something different. Notice that each time you edit a copy of the card, a bright "*" appears on the statusbar . This is the flag to say that the copy of the card in that window has changed since it was last saved to disk. To continue the experiment, switch back to window 1 and type, "This is the copy I want to keep." Check the other windows and verify that in each one you have a different copy of the same card, each still containing whatever changes you made there. Finally, return to window 1 and press <F2> to save it. NOW check the other windows and see what has happened! When you saved the copy in window 1, Orpheus updated the other windows to contain the same version. This is one of several ways in which Orpheus protects you from losing your work. Here's another one: still in the Homecard, type some gibberish to make a nice mess; we'll pretend that you've worked on this card for hours and now it's ruined. Press <Alt-F> to open the File Menu, then press <R> to select "Reread From Disk". This restores your Homecard from the copy you saved. One Step "More" Before concluding this chapter, let's make one more link: specifically, a "More" link. Switch to window 1 and jump to the Homecard if you are not there already. Currently the Homecard displays a title followed by a line of text with a linkword in it. Now, suppose you want your title screen (the Homecard) to have JUST the title, with perhaps a nice drawing and your name. Suppose too that you want that line of text to become a couple of paragraphs, even a menu -- something in any case that would not be very effective on your title screen. We're going to see how Orpheus gives you the flexibility to change and extend your hypertext without starting over. We'll do this by creating a new linked card and automatically transferring the line of text, together with its linkword, onto that card -- all in one step. Currently we have this: And it's going to become this: +==========+ +==========+ | Homecard | | Homecard | | door1 | | "More" | +====|=====+ +====|=====+ +====|=====+ +====|=====+ | Child 1 | | new card | | door2 | | door1 | +====|=====+ +====|=====+ +====|=====+ | Child 1 | | door2 | +====|=====+ 21 To begin, place the cursor on the line of text with the linkword, i.e. anywhere on "...and here is door1 in it." Now press <Alt-L> to open the Link Menu and select "Split", because we're going to "split" the Homecard. A submenu opens with three options: Above, Below, and At the Cursor. Press <C> to select "At the Cursor". This tells Orpheus not only to split the Homecard, but to take ALL text from the cursor on down and move it to the new card along with whatever embedded links it may contain. You'll notice that this time there isn't a dialog asking if you wish to resize the linkword; the reason for this will become clear in a moment. The familiar "Jump now?" dialog does come up however, and this time I'd like you to press <1> to ensure that you jump to the new card without switching windows -- just so you'll know that you can do it. What has happened? The line "...and here is door1 in it" is now in a new card all by itself. To find out what happened to the Homecard, press <PgUp> or <Home>. As you can see, an additional change has occurred: not only is "THIS IS THE HOMECARD" all by itself, but there is a "More" flag on the statusbar. As I explained in the previous chapter, this means that the Homecard has a "More" link, which would appear to the reader as the word "=More=" in the lower right corner. In the Orpheus Reader the "=More=" flag works just like a linkword, meaning that you can jump through it by clicking on it, or by moving the selection bar to it and pressing <Enter>. In OH.EXE we use the <Right> arrow key for this purpose (as always, on the number keypad), or you can click on the word "More" on the statusbar. Try this now. Behind The Scenes In this chapter you have seen how easy it is to make hypertext in Orpheus. You didn't have to type in any filenames or special codes, you didn't have to do any programming; yet somehow links got made, and apparently something got written to disk. Orpheus frees you from having to think about the mechanics of hypertext. Even so, you should probably have some idea of how Orpheus manages your hypertext cards. Here's what went on behind the scenes: (1) When you made that first link in your Homecard, Orpheus took the filename you gave it, "TEST", and created a *project* directory named after it but with an underscore as the last character. If your Orpheus directory is C:\ORPHEUS, this resulted in C:\ORPHEUS\TEST_. Orpheus then went on to create the first *storage* directory in the project directory, giving it the name D1 (for "directory #1"): C:\ORPHEUS\TEST_\D1. (2) With the directories in place, Orpheus made a file for the new blank card, giving it a name drawn from the linkword, "door1", followed by an extension representing the number of that link. The new file, empty except for the information linking it to the Homecard, was thus named DOOR1.000 and written to disk in the C:\ORPHEUS\TEST_\D1 directory. 22 (3) Orpheus then embedded the same link number in the Homecard, added some other data, and immediately wrote to disk the file TEST in your working directory, C:\ORPHEUS. Note the pattern here: the Homecard is the only file you need to "know about", and it remains in your working directory where you can find it easily. All cards (files) linked to the Homecard are stored off a subdirectory named after the Homecard, and you can leave the management of them entirely up to Orpheus -- even when it comes time to delete them (see "Erase Project" on the Project Menu). You can have as many electronic books on the go as you wish, each one having its Homecard in your working directory; the cards in one book never get mixed up with the cards from another. (4) Lastly, Orpheus wrote to disk a file called TEST.LST, the "list file" of the Test project. Though list files are always the same size, they are updated whenever you create or delete a card, and they help Orpheus track up to 32,000 linked cards. With each of the other links you made in this tutorial, Orpheus again wrote to disk the new blank card, the card containing the link, and the updated list file. What happens when a book gets really big? Do all those cards go into the D1 directory? And what about when you finish a book and want to distribute it to readers -- do THEY have to worry about a thousand separate card files? No. When Orpheus compiles your book (see the Project Menu) it compresses it into a small number of special files. Each book consists of one file with the HTX extension, plus one or more numbered data files containing your cards in compressed form. As for the previous question, when the "D1" directory holds 100 cards Orpheus will create a second storage directory named "D2", and so on up to D320 for a maximum capacity of 32,000 cards per book. (Note however that books can be linked to *other* books. See the load() command in MANUAL2.DOC.) When We Return... Let's end this tutorial and leave your work so that you can come back to it later. (Even if you're gung-ho to work right through, follow these instructions and then reload the program as described below.) To make the project look a little more realistic, switch to the other 3 Edit windows and make sure they all contain different cards. For example, leave window 1 containing the Homecard, and window 2 containing the line with "door1". I'd like you to end up in window 2 before we quit, because there's something I want to demonstrate. All set? Press <Alt-F> to open the File Menu, then press <X> to quit the program. (You could also just press <Alt-F4>.) You'll notice one final bit of disk activity, which is Orpheus saving a file named TEST.PRJ. For each electronic book you work on, Orpheus creates a "project" file named after the Homecard and with a ".PRJ" extension. This file records all of your option-settings for that book, as well as the "state" of the project when you were last in it: the contents of the four Edit windows, and which window you were in when you quit. 23 When you return to your "TEST" book in the next tutorial, you will again start up Orpheus with the name of the book at the DOS prompt: OH TEST This time, Orpheus will detect the existence of your book and will load the four Edit windows exactly as you left them. If you were in window 2 when you quit, you'll find yourself there again when you return. 24 --------------------------------------------------------------------------- CHAPTER 4 - TUTORIAL : FLEXIBLE HYPERTEXT --------------------------------------------------------------------------- Topics in this chapter: Importing Text Moving Links Splitting Designating Home Crosslinks & Retrace Resizing Linkwords Changing Link Types Unlinking Recovering In this chapter we'll continue with the test book begun in the previous chapter. Load it with the same command at the DOS prompt that you used before: "OH TEST" <Enter>. You should find yourself in the same Edit window as the one you were in when you quit, with all windows loaded the way you left them. Importing Text Orpheus makes it easy to write directly in hypertext -- but doesn't oblige you to do so if you would rather use text from external files. As long as your text is in plain ascii form (without special formatting codes from a word processor) you can import it chunk by chunk into your hypertext cards. Some word processors normally save files in the plain text form required by Orpheus; an example is PC-Write, which only inserts formatting codes if you tell it to, and also lets you remove them. Other word processors normally save files in a proprietary format in which the text is interspersed with formatting codes. The better ones allow you to save a copy of a file without these codes, referring to this as "text", "ascii", or "non-document" mode; an example is WordPerfect. To view an external file in Orpheus, use the FileView window; this is represented by the "V" in the "1 2 3 4 V" cluster on the statusbar. FileView does not permit any editing of the files you load in it; what it does do is let you capture chunks of text (up to 23 lines at a time) and import them into your work. You can open FileView through the Window Menu, but there are a couple of faster ways: press <Alt-V>, or just click the left mouse button on the "V" on the statusbar. Do this now to begin the tutorial. Since nothing is loaded there yet, a dialog appears asking you to enter a filename. If you wish, you can press <F8> to get a directory listing, or enter "manual1.doc" -- the name of the Orpheus User's Guide. In what follows I'll assume that this is what you're using. 25 When the file is loaded, experiment to see how you can scroll up and down to read it. Since you're not in an Edit window, you can use the keys of the number keypad if you wish. Mouse-users can click on the symbols on the command bar at the bottom. Press <F1> for context- sensitive help on how to use FileView. In a moment we'll mark a block of text in MANUAL1.DOC and paste it into one of your hypertext cards. Let's switch back to the Edit window you were in to see if the card we want is loaded. <Alt-V> got you into FileView and will also get you out of it, but as you can see at the bottom of the screen, you can also press <R> or click on the "Return" command. Back in the Edit window, are you looking at the card with the line "and this is door1 in it"? If not, navigate to it as you learned in the previous chapter, using the number keypad or the mouse. Now switch back to FileView and page down to the Table of Contents, far enough to place the topic list for Chapter 1 in the middle of the screen. We'll pretend that this will be the Main Menu for an electronic book. We'll mark those lines, return to the Edit window, and paste them in. I'll show you the keyboard method first, then the mouse method; as part of the exercise we'll find out how text marked in FileView is treated when we paste it into an Edit window. KEYBOARD METHOD - MARKING IN FILEVIEW Notice that the cursor is at the far left of line 1. Assuming that the lines you wish to mark are in the middle of the screen, you'll want to move the cursor down. In FileView the up/down arrow keys do double duty, moving the cursor as far as the top and bottom lines, then scrolling the text. After moving the cursor to the line beginning "Chapter 1", press <F3> to start marking (or any other key that you would use for marking in an Edit window). Move the cursor to the last line of the contents of Chapter 1, and press <F3> again to finish marking. MOUSE METHOD - MARKING IN FILEVIEW With the mouse pointer on the line beginning "Chapter 1", press and hold down the right mouse button to start marking. Keeping the button depressed, drag the pointer to the last line of the contents of Chapter 1, then release the button to finish marking. With the marked block ready, press <R> or <Alt-V> (or click on "Return") to return to the current Edit window. Just to demonstrate what you can do, we'll pretend to paste the block into the middle of your line of text. KEYBOARD METHOD: move the cursor into the middle of the line of text, then press <F3> to paste. MOUSE METHOD: move the mouse pointer to the middle of the line of text and click the left button to paste. 26 Notice that instead of being dissected by the inserted block, the line on which you placed the cursor was simply pushed down by it. This is because blocks marked in FileView are treated as whole lines. In other words, FileView marking is done in "line mode", which we'll discuss in the next chapter. Press <F2> to save. With a little practice you'll find that by using FileView and the techniques shown above, you can rapidly convert an ordinary file into hypertext. An even faster method is to use the AutoMark button on the command bar, which instantly marks all 23 lines onscreen. Use the Up/Down arrow keys to reduce an AutoMarked block, and PgUp/PgDn to restore it. AutoMark also lets you use AutoMORE, which is discussed in online Help. Moving Links The line with "door1" looks rather out of place just now, so let's move it somewhere else. We'll pretend that after making a quick start on our book we've had enough time to think about how it should be organized, necessitating some changes. This isn't the best way to work, but let's face it -- no matter how much planning you do, inevitably you'll want to move things around. Orpheus lets you do it without hassle. We'll pretend that "door1" is really a topic you want to discuss under "Quickstart". This means we need to open a link off "Quickstart" and then move the line with "door1" to it -- not just the words, but the embedded link as well. First, place the cursor on the word "Quickstart" and open a Door link as you did in the previous chapter: press <Alt-L> to open the Link Menu, press <Enter> to choose the "Door" link type, and press <Enter> again to accept the default size for the linkword. At the "Jump now?" dialog, select a window number *other than* the current window. When you are in the new blank card, switch back to the window you started from. (The fast way to do this is by pressing <Ctrl-V>.) You should now be looking at the topic list for Chapter 1, in which the word "Quickstart" is a linkword. Below the list is the line "and this is door1 in it". We're going to move that line, together with its embedded link, to the card you just created. Place the cursor anywhere on that line and press <F7> to start marking in line mode. Without moving the cursor, press <F7> again to finish the mark on that line. Now switch back to the window with the new card and press <F6> to MOVE the marked line from its original location to the new one. Something extra happened: after you pressed <F6>, Orpheus posted a message saying "Verifying chain of links." Then there was a bit of disk activity. This was because your marked block contained an embedded link, so in moving it to another card you were in effect "pruning and grafting" -- like cutting a branch off a tree and inserting it somewhere else. Before letting you do this Orpheus made sure that it would not break the chain of links connecting every card to the Homecard. 27 Navigate up and down a few steps to verify that the link itself was really moved. To summarize, here are some points to remember with regard to moving embedded links: (1) both cards involved in the move must be loaded simultaneously in separate Edit windows; (2) you can use any marking mode; (3) it's safe: if you attempt a move that would disconnect a branch from the Homecard, Orpheus will discover the danger and abort the procedure. Splitting In the previous chapter we used the "Split" command on the Link Menu, mainly in order to show you what a More link looked like. You'll recall that we used the subcommand "Split At Cursor", which simultaneously created a new card and moved some text to it -- our ill-treated line with "door1" in it. Now we'll use another variation of splitting to demonstrate the versatility of this feature. Press <Home> or navigate up to the Homecard, then press the <Right> arrow or click on "More" to jump down a step. This should bring you to the card with the contents of Chapter 1, which is our make-believe Main Menu for a vast electronic book. Let's pretend that you wish you could insert something _between_ these two cards: say, an epigraph, acknowledgements, or a copyright notice. Wish no more... Open the Link Menu and select "Split", but this time select "Above This Card". At each dialog press <Enter> until the process is complete, which should leave you at the new blank card that has been created. Now press <Alt-V> to switch to the FileView window. Page up until you find one of the paragraphs on the first page of the manual; the one beginning "Orpheus makes you a master of hypertext" is suitable. Mark the paragraph as you did before, then return to the Edit window and paste it wherever you wish with <F3> or the mouse method. Now jump to the Homecard and work your way down, see how it feels. The important thing here is that we've replaced the infinite linear extensibility of conventional text with something better. You don't have to feel cramped by the dimensions of the screen or of a card, yet you don't have to resort to scrolling files. Designating Home Navigate to the card with the contents of Chapter 1. Imagine again that this is your Menu, through which readers will pass to all the different branches of your book. Now think of yourself as a reader, exploring a branch all the way to the end; at some point, and this may happen repeatedly, you'll want to jump back to the beginning in order to set off down a different path. This means pressing <Home> of course, which currently takes you to the Homecard. But it makes no sense to keep jumping to the Homecard if all it has is a More link followed by another More before you get to the menu again. 28 This is why Orpheus lets you designate a card other than the Homecard to be the destination of a jump Home. Press <Alt-P> to open the Project Menu; notice that the field opposite "Designated Home" says "None". Select this option now, and when Orpheus asks whether you wish to use this card as the Homecard, press <Enter> to answer Yes. From now on, whenever you open the Project Menu the field will say "Here" when you are in the Designated Home card, or "Yes" when you are in any other card. To test the new setting, navigate down through all the links you can find, then press <Home>. You should jump to the card with the contents of Chapter 1. If you press <Home> again however you'll jump to the real Homecard, while doing so again will take you back to Designated Home. This feature and the next one help you make hypertext navigation more natural and meaningful to your readers. Crosslinks & Retrace So far, all of the links you have made have had a "child" relationship with the cards in which you made them. Whether you jumped through a linkword or a More, pressing <PgUp> would always take you back to where you began by following the chain of "parent" cards. Crosslinks introduce a new factor; because they join *existing* cards, a jump through a crosslink cannot be reversed by pressing <PgUp>. For this reason Orpheus maintains a record of your steps in all directions -- down, up, and crossways -- and allows you to retrace as many of your steps as are in the record. When you reach the end of the record Orpheus gives a "click" (a "bonk" on slow machines). On the number keypad the <Left> arrow gives the Retrace command; its mouse equivalent is the U-turn symbol on the statusbar. In OH.EXE there is a separate Retrace buffer in each Edit window, each one large enough to record your last 50 steps. The Orpheus Reader has a single Retrace buffer that records your last 100 steps. Since the Reader uses the arrow keys to give more subtle control over the movement of the selection bar (side to side as well as up and down), retracing with the keyboard in that program is done with the <Backspace> key. Before we get into making a Crosslink, let's consider how Crosslinks might affect the quality of your hypertext -- the impact they might have on your reader. Suppose a certain topic is discussed thoroughly on one particular card. Suppose further that you refer to that topic in passing on many other cards. At first glance it might seem reasonable to open a Crosslink on each of those references, so that the reader can jump from any of them to the card where it is discussed. But let's suppose further that you have many such topics, and that on any given card you might see a scattering of linkwords, some pointing to unique material, others pointing through Crosslinks to cards that the reader may have visited already. Such hypertext quickly begins to feel like spaghetti. Where Crosslinks are numerous you can't expect the reader to remember which ones he has taken (and should therefore ignore) and which he has not. Every 29 linkword is like a doorway beckoning, "Enter here!" If the reader repeatedly responds to the invitation, only to find himself in a place he's been already, he will become frustrated and bored, mistrustful even of linkwords that lead to something new. My advice is therefore to use Crosslinks sparingly. But if they were entirely bad they wouldn't be on the menu, so let's see how to make one in a situation that makes sense. Navigate from the Chapter 1 card through the "Quickstart" linkword. Though all we see is that poor forlorn "door1" we'll pretend that this card is yet another menu. (To make this more believable, type in "Variations on Quickstart". Not much more believable than a paid political advertisement, but cheaper.) The idea here is that you've organized a large amount of information so that the reader can find just about anything with three or four clicks of the mouse: each item on the Main Menu leads to a submenu, which may in turn lead to deeper submenus. Now, in the same way that it is useful to designate the Main Menu as Home, you may find it useful to let the reader jump from a location at the end of a branch to a particular submenu, or the *beginning* of that branch. This is one good use for a Crosslink -- to return quickly from the end of a branch to its beginning. Leaving the Quickstart card where it is, switch to a different Edit window and navigate down as far as you can go -- i.e. to a card that is a few levels down from Quickstart but on the same branch. (As you will see, there is a reason for doing this in another window.) Move the cursor down to within a few lines of the bottom, then type, "Return to Quickstart". We're going to make a Crosslink on that, and point the link back to you know where. Now open the Link Menu and select "Crosslink". A submenu will open, from which you should select "One-Way Crosslink" (I'll explain this in a moment). Now Orpheus asks you which window contains the OTHER card, meaning the one to which the Crosslink should point. Notice that the hilited window-number is that of the last window you were in, which should be where you left the Quickstart card; press <Enter> if it is. The next step is to select a linkword, and for Crosslinks Orpheus lets you move the cursor around instead of automatically taking the word at the cursor. (The prompt for this mentions the "1st" linkword because a Two-Way Crosslink requires two -- one in each card.) Place the cursor on "Return" and press <Enter>, then press <Enter> again to accept the default linkword size. This completes the procedure. Test your Crosslink by jumping through "Return". As you'll see, the only way to retrace the jump (in one step) is to press the <Left> arrow or click on the U-turn symbol on the statusbar. If you think about it, you can see why a One-Way Crosslink is appropriate for the situation in the example. A Two-Way Crosslink would result in each card having a Crosslink pointing to the other, which in 30 this case would make no sense, though in others it might. While Two-Way Crosslinks may at first glance seem "friendlier" (since they provide an obvious return instead of requiring a Retrace command), they could also lead to an unnecessary proliferation of linkwords. If you must use Crosslinks, use them judiciously! Resizing Linkwords Throughout these tutorials I've kept things simple by having you accept the default options during linkmaking. This is the same approach you'll take when ideas are coming fast and furious and you don't have time to worry about details. Now and then however, as you go over your work looking for areas to revise or expand on, you'll notice a detail that deserves an extra touch: the size of a linkword. Linkwords can in fact be "link phrases", meaning that they can include several words; the only thing they can't do is extend to another line. A good candidate for resizing is the Crosslink you just made. Navigate to it now if you are not there already, and press <Down> to place the cursor on the linkword. Now open the Link Menu and select "Resize a Linkword". From this point on the procedure is identical to what you would do if you chose to resize while actually creating the original link. (By the way, though the dialog doesn't say so you can get Help on what to do by pressing <F1>.) In this case it would be nice to expand the linkword to the right, so that instead of just "Return" it would be "Return to Quickstart". Before doing this however, there is an important point to consider regarding colors. Color attributes consist of both a foreground and a background. If the background attribute of a link color is DIFFERENT from the background of normal text, a space is plainly visible; but if the two backgrounds are IDENTICAL, a space in "link color" looks the same as one in normal text color. Keep this in mind whenever you resize a linkword. Unless you can tell when resizing has extended to a space, it is easy to leave the linkword lopsided. In your own color scheme you can't see it, but hundreds of readers with other color schemes surely will! KEYBOARD METHOD - RESIZING Press <E> for "Expanding". Now press and release the <Right> arrow key repeatedly to extend the hilite one space at a time toward the right. If you go too far, press <S> for Shrinking and again use the right arrow to retract from the right. (The right arrow affects the right side of the linkword, the left arrow affects the left side.) Press <Enter> when done. MOUSE METHOD - RESIZING Click the left button on the "Expanding" command. Now move the mouse pointer away from both commands and click the right button repeatedly to extend the hilite one space at a time to the right. 31 If you go too far, click on the "Shrinking" command, move the pointer away from both commands and again use the right button to retract from the right. (The right button affects the right side of the linkword, the left button affects the left side.) When the linkword is the desired sized, click on the "Enter" command. To reduce the risk of error, consider setting your colors so that linkwords are clearly distinct from normal text. (To change your colors, open the Options Menu, select "Screen", then "Colors".) Changing Link Types Before proceeding with this part of the tutorial, you may wish to read about the 7 different link types available in Orpheus. They are thoroughly discussed in online Help so I will not describe them here. (Look in Help under "About Hypertext" => "Link Types".) With certain restrictions it is possible to change a link from one type to another. Action, Init, Graphic links, and Crosslinks CANNOT be changed to another type, for reasons that become apparent when you understand what they are. This leaves Door, Note, and More links, which CAN be changed. The commonest motive for changing a link's type involves the difference between Door and Note links. Doors are the "normal" link types in Orpheus, while Notes are intended to suggest a more detailed level of information. Another use of Notes is provided by the "Include Notes" option on the Project Menu: if this option is turned off (so that the field is blank), when you compile your book it will not include any trace of Note links or of the cards descending from them. (Compilation does not affect your working copy of the book, where the Notes are left intact.) This lets you use Note links for your "working notes" during composition, or more importantly, lets you release different versions of your book. For example, suppose a client calls, wanting you to send over a disk with your work in progress; some major bucks depend on making a good impression, and you're confident that most of the book will do just that. BUT, one branch near the beginning is still in rough shape, and you'd hate for your client to see that. Solution: turn the Door link at the top of the branch into a Note, de-select Include Notes, and recompile. (Another method is to Unlink the branch, as discussed on the next page.) Let's change a link type now to see how easy it is. Navigate to the card with the unfortunate "door1" in it, and place the cursor on that linkword. Open the Link Menu and select "Change Link Type". A dialog pops up, in which you'll select "Linkword at Cursor". This is followed by another dialog giving you the choice of changing it to a Door, Note, or More link. Select "Note" in this case. That's all there is to it! If you change your mind later you can change the link type back again. 32 Unlinking Among the many ways you can revise your work in Orpheus, one of the most powerful is the ability to remove a card, or even a whole branch of cards, from your hypertext network -- and do so either temporarily or permanently. This is called Unlinking, and it comes in two flavors depending on the fate intended for the attached card. If you choose to "Orphan" it the card remains on your hard disk, with a slight change to its filename so that Orpheus can recover it for you later if need be. If you choose to "Delete" it the card is really deleted, and even if you retrieve the file with an Undelete utility there is no easy way to relink it to your hypertext. Actually there is a third flavor of Unlinking: when you unlink a Crosslink the only change is to the linkword, which loses its embedded link data and returns to normal text. The linked card is unaffected, except when you have a Two-Way Crosslink, in which case you are given the option of automatically unlinking the other card's Crosslink as well. All links can be Unlinked, but not all can be deleted. As a safety measure, Orpheus does not let you delete a card that has child links of its own; such a card can only be orphaned. Let's try this now, and in the next section we'll use the Recover command. Navigate to the card with "door1" and place the cursor on the linkword. It's time to put it out of its misery. Open the Link Menu and select "Unlink". From the ensuing dialog, select "Linkword at Cursor". From the next dialog, select "Orphan". That's all there is to it. However, you may wish to revise the text to read, "Door1 is no longer in service. Have a nice day!" Recovering As long as an unlinked card is not deleted, you can easily recover and relink it. If you have unlinked many cards you may wish to simply browse them at some point to see if there are any you want back; note however that there is no way to browse the *descendants* of an orphaned card without first relinking it. When you know you want to relink an orphaned card, the first thing to do is to navigate to the card *to which* you wish to relink it -- before opening the Recover dialog. For the next exercise we'll assume that you are still in the card where you unlinked "door1". Open the Link Menu and select "Recover Orphan". The Recover dialog displays two lists: in one box, the list of storage directories for your book, and in the other box the list of orphans found in the currently hilited directory. At the moment only 1 directory exists, "D1", and it should contain only 1 orphan, which is probably named "DOOR{.000". The "{" character in the filename is what marks it as an orphan. 33 When there is more than one directory you can scroll through the directories using the PgUp/PgDn keys. When there is more than one orphan in the listed directory you can scroll through the filenames using the Up/Down arrow keys. Since you've had a change of heart about door1, press <L> to relink it right away. A dialog appears with a choice of link types; select "Door" to give it its old job back. Next a prompt appears on the top line, asking you to select a linkword to anchor the link. Assuming you followed my advice at the end of the previous exercise, move the cursor to the word "service", then press <Enter>. (We'll be sensible and make it a service door.) Now the familiar Resize dialog appears, and in this case you can just press <Enter> again. Done! Normally you would relink an orphan to its original linkword in the original parent card; however, nothing obliges you to do so. As a matter of fact, relinking to a different card, perhaps in a completely different part of your work, is an effective method of pruning and grafting when all you want to move is the link and not the text. 34 --------------------------------------------------------------------------- CHAPTER 5 - TUTORIAL : COMPLETING A PROJECT --------------------------------------------------------------------------- Topics in this chapter: Sweating The Details Copyright Cardlength Full Title Include Notes Your Colors Graphic Titlebar Check the "More" Corner Check the Frame "Check Card" Command Check Linkwords Use Tour Mode Compiling Your Project Distributing Your Work The Orpheus Reader Cleaning Up Though there remain many aspects of Orpheus that we haven't yet touched on, it's time to look at how you can get an end product from your labor: something that (if you are a registered user of Orpheus) you can distribute to other people. Note that you can compile your work as often as you want while actually writing it, if only to see what it looks like in the Reader. The compilation process is non-destructive: your working version remains untouched, and the compiled version is kept separate. Sweating the Details : Copyright I often hear young writers and programmers asking how to copyright their work. The best method is to post a copyright notice in the work itself. In printed books, this usually goes on the reverse of the title page. In electronic books, put the copyright either on the title screen or one following shortly thereafter. All it takes is the word "Copyright", the year, and your name or that of a publisher. "Don't you have to register it somewhere? Don't you have to get a certificate that SAYS you have copyright?" Absolutely not. Just post the notice, and (as long as it's your own work) you have legal copyright. Even if you plan to give your work away or distribute it as shareware, I **STRONGLY** urge you to place a copyright notice early in your document. This does not prohibit your readers from helping to disseminate your work if you wish them to do (as shareware or public domain hypertext). Nor does it conflict in any way with the copyright on the Orpheus Reader, which is held by Hyperion Softword. 35 Cardlength If you have read the section on Workspace in Chapter 2, you know that when you compile your work for viewing with the Orpheus Reader, only the top 24 or 25 lines of each card are included in the finished version. The default cardlength is 24 lines; this leaves space for the Reader's titlebar, which displays a menu prompt, the full title of your work, and some command buttons for navigating with the mouse. If you select a cardlength of 25 lines, the titlebar only appears when the user presses <Esc> or clicks the right mouse button; the rest of the time, the entire screen is given over to your work. To verify your cardlength setting, open the Project Menu. Selecting "Cardlength" toggles the value between 24 and 25. This has no effect on the appearance of your work in the Orpheus Author, except when you use the Check Card command (discussed below). Full Title Filenames in DOS are so short that it can be hard to make them informative. At first glance you might think Orpheus makes it even harder, since the name of your Homecard is limited to a maximum of 8 characters. The Project Menu offers a solution: select "Full Title" and enter up to 32 characters. For our demonstration book you could type in "This Is A Little Test". This title will be displayed on the titlebar when your work is viewed with the Orpheus Reader. Include Notes If you use Note links in your work, open the Project Menu and check whether the "Include Notes" field is selected or blank. The default setting is for it to be selected. Possible reasons to de-select it would include: (a) your Notes are for your own use and are not intended to be seen by the reader; or (b) you wish to make a selective compilation, "hiding" one or more branches that begin at Note links. Your Colors If you want people to see your work in YOUR colors rather than in the Orpheus Reader's default color scheme, select "Your Colors" on the Project Menu. If you do not, make sure the field is blank. Since the Reader still permits users to adjust the colors themselves, you don't really have to worry about people finding your scheme illegible or hard on the eyes. They will see your colors first, and if they don't like them they are free to choose their own color scheme. 36 Graphic Titlebar If you display graphics or ansi screens from Graphic cards, your readers will have the option of using the Graphic titlebar for navigation and to open the menu. Normally in Graphic cards the titlebar is hidden: the entire screen is given over to your graphic or ansi screen. To reveal the titlebar the reader must move the mouse pointer to the top of the screen. If your graphics do not have to extend to the top of the screen, and if you are concerned about making your work as user-friendly as possible, select "Graphic Titlebar" on the Project Menu. This will ensure that the titlebar is always visible when the user is in a Graphic card. (Note however that this does not apply to graphics or ansi screens displayed from Action or Init cards.) Check the "More" Corner If you use More links, remember that in the Orpheus Reader the More flag appears in the lower right corner and takes up 6 characters: =More=. In contrast, Orpheus Author displays the flag on the statusbar, which could lull you into a false sense of security. What if you've written text into what will be the lower right corner of a card, and there's a More link? Keep this in mind when using the Split command or when adding text to a card that has a More Link. Check the Frame If you select the Frame option on the Project Menu, which tells the Orpheus Reader to display all text cards within a frame, you should check your cards to see whether any text or linedraw characters appear in the top or bottom lines, or against the left or right edges of the screen. You CAN leave text there if you wish, "embedding" it in the frame as discussed in online Help. This can be a desirable effect if it's what you want to do; just make sure that anything in the frame area is there because you want it there. "Check Card" Command The Check Card command (on the Tools Menu) temporarily displays your card as it will appear in the Orpheus Reader. If the card has a More link the =More= flag is displayed in the lower right corner. If the cardlength setting is 24 a simulation of the Reader's titlebar replaces the statusbar, while if it is 25 the statusbar is hidden. If a frame is installed (see above) the chosen frame is drawn. Pressing any key restores the normal display. If you give the Check Card command while in a programmable card, Orpheus attempts to perform the entire script (sequence of commands) in that card, notifying you if it encounters any errors. Certain commands such as jump() cannot be performed in OH.EXE, but the majority can. For 37 example, Check Card gives you an accurate performance of scripts involving graphics, ansi screens, special effects, timed pauses, and music. Check Linkwords As mentioned in Chapter 4 under "Resizing Linkwords", if the background color for a linkword is the same as that of ordinary text, and if you decide to resize the linkword, you can easily make the mistake of going too far on one side or the other -- giving the linkword an extra space. For those of your readers who choose colors in which the backgrounds are different, that space will be all too apparent, and your electronic masterpiece will look sloppy. (Orpheus never includes extra spaces when it selects the default linkword, so if you never resize your linkwords you don't have to worry about this.) Whether your intended readers are the general public or the co-workers in your office, you want your work to be as sharp, effective and professional-looking as can be. My advice is to configure your colors in Orpheus Author so that all linkwords are set on a background distinct from that of ordinary text. Use Tour Mode The Orpheus Reader provides an additional tool to help ensure that your work comes out exactly the way you want it. After compiling your project (see below), load it in the Reader and select "Tour" from the Reader's File Menu. This opens the Tour Menu, which lets you set up an automated tour of your entire book. The most practical method is to select a Sequential tour with the delay option of your choice. When you press "Go" the Reader starts from the Homecard and proceeds to follow the chronological sequence in which you created your book. When it reaches the end it starts over from the beginning, making it easy to tell when you've seen everything. Note that the Reader does NOT activate either Init cards or Action cards when in Tour Mode, since these could contain commands that would interrupt a tour. If you have used Init or Action links and wish to inspect them, wait till the tour brings you to a card that has one, and press <Alt-T> to leave the tour. Use the same method if you wish to pause to identify a card that needs changes. To continue from where you left off, open the Tour Menu and press "Go" again. Tour Mode is designed to avoid unpleasant surprises; if it encounters a bad link (meaning a card that it cannot find or read) it ignores it and tries the next link. This is no help when you're proofreading, so there is a special command you can use to tell the Reader to STOP at a bad link. Here's what to do: with the Tour Menu open, hold down the <Shift> key when you press "Go" to start the tour. A message will pop up saying "Proofing On". Press any key to let the tour proceed. Now 38 if the Reader encounters a bad link it will stop at the card BEFORE that link and post a message; this automatically pauses the tour as if you had pressed <Alt-T>. Press any key to clear the message, and note the path to the card where the tour stopped (this is so you can navigate to it later in OH.EXE). Now open the Tour Menu, and WITHOUT holding down <Shift> press "Go" again to continue the tour; proofing is still on, and the Reader automatically goes to the next link after the bad one. (If you hold down <Shift> the second time, proofing is turned off.) Proofing with Tour Mode gives you the assurance that all of your text and Graphic cards have been correctly compiled for viewing in the Reader. Remember that Init and Action cards are not tested in Tour Mode, nor are Crosslinks, so a complete proofreading must be done manually. If a Crosslink leads to a bad link or to a different card than you intended, it means that you orphaned or deleted that card and forgot to unlink the Crosslink; the solution is to unlink it and recompile. In ALL other cases, as of version 1.41 of Orpheus there should NO possibility of bad links making it into the Reader. (If you encounter an exception, please call Hyperion Softword at 1-819-566-6296.) Compiling Your Project At any stage during your work on a document, you can compile it to see how it looks in the Orpheus Reader. The process is identical whether you are finished or not. (Compare this to publishing in print: before you spend a bundle at the printer's, you *hope* that manuscript is perfect!) To compile a project, load it in the Orpheus Author the way you would for a normal working session. Open the Project Menu and select "Compile Project". It doesn't matter which card you're in. Orpheus asks "Are you sure?". Press <Enter> to say Yes. Now Orpheus asks if you have verified your project options. Assuming that you have checked everything as described earlier in this chapter, press <Enter> to answer Yes again. Now Orpheus gets busy, as you can tell from the activity on your hard disk. Just sit back and watch -- that's all you have to do. In step 1, Orpheus displays a message saying that it is "Building the compilation list". This is a list of all of the cards that will go into the compiled version of your work. Orpheus starts from the Homecard and works its way down, verifying every link and adding each card it encounters to the list; if it comes to a Note link and the Include Notes option is turned off, Orpheus ignores that link and everything it might lead to. In step 2, Orpheus displays a window in which you can monitor its progress as it creates your finished work. For our test project this will go by in a matter of seconds. In step 3, if all has gone well, Orpheus says "Compiled successfully!" Press any key to continue. 39 In step 4, Orpheus informs you that it has created a file containing a list of everything that should go into the distribution package when you send your work out into the world. This file is named after the Homecard and has a .DOC extension, so for our test project it would be called TEST.DOC. Please note that the DOC file is for *your* use and should not be included in the distribution package. (By "distribution package" I mean whatever you use to distribute your work, such as a floppy disk or a ZIP file. This is discussed in the next section.) Let's look at the DOC file. Switch to the FileView window and load TEST.DOC or whatever name was given in the last message. There are three groups of files in the list: your compiled hypertext, your graphics if any, and the Orpheus Reader. The first group always consists of at least two files, of which the first ends with an .HTX extension, while the remainder are numbered. In this case the list will show TEST.HTX and TES_.1. The second group lists the graphics in your book (if any). The last group of files consists of the executable and help for the Orpheus Reader: OHREAD.EXE and OHREAD.HLP. Distributing Your Work If you are a registered user of Orpheus -- meaning that you have paid the registration fee to Hyperion Softword and have received a licence in return -- you have the right to distribute your work in compiled form together with the Orpheus Reader. This right is unrestricted: you may distribute as many copies as you wish, and you may do so in any way you wish, whether by selling it, giving it away, or putting it out as shareware with whatever registration fee you choose to specify. If you are not a registered user of Orpheus, you may not distribute your work in ANY form, whether compiled or uncompiled. There are two steps involved in distributing your finished work. The first is to put together a package. The second is to get it out into the world. Look back over the better pieces of software you've encountered: the good ones always have a certain neatness about them, something that satisfies the veteran while reassuring the novice. It should all hold together, it should be well documented, and it should be as easy as possible to start up and to use. As suggested in the DOC file created after compilation, your software package should always include a README file. You can prepare this using your favourite word processor, but remember to save it to disk in non- document mode, i.e. as a plain ascii text file. The README file should include the following: (1) a brief explanation of what the work is and how to start it; (2) a "packing-list" giving the name (and optionally the size) of every file that the user should find in the package; (3) a copyright notice identical to the one posted near the beginning of your document; 40 (4) if you are distributing the work as shareware or freeware, a statement to that effect, with (for shareware) the registration fee; (5) optionally, your name and address if you want your readers to be able to contact you; (6) if your book includes graphics, a statement of the minimum hardware required to view your work without missing anything. If you just use a few graphics and they don't have any hotspots, this is not required. Along with a README file, many software developers include a GO.BAT file, especially when the software is distributed on disk. When a novice user sees the instructions "Type GO <Enter>" right on the label, he knows exactly what to do. Your GO.BAT file would contain the command to start up the Orpheus Reader with your document. In the case of our "Test" project, this command would be "OHREAD TEST.HTX". In other words, if the user types "GO" <Enter> at the DOS prompt, this starts up GO.BAT, which in turn passes to DOS whatever commands you place in it. If you're not familiar with batch files (files with a .BAT extension), read about them in your DOS manual. If you're a power user, you know that you can make a batch file do some pretty fancy things. For example, with the addition of a utility like REPLY.COM you can write a batch file that accepts user input and branches accordingly. Your GO.BAT could let the user either view the README file first or immediately start the program. Is this beginning to sound complicated? Relax... You don't have to have a GO.BAT. All the user needs to do is type "OHREAD" <Enter> at the DOS prompt, and the Orpheus Reader will take it from there. When you pass the Reader the name of a book complete with .HTX extension, it loads the document immediately; otherwise, it searches the current drive/directory for HTX files, then displays a directory dialog to let the user choose from what it finds. It does the same thing if you give it the wrong type of filename, so even novices can't get into trouble. There are many ways to put your work out into the world, some of them easier than others, all of them cheaper than print media. Perhaps you are a consultant and you are creating an electronic book for your clients; perhaps you are creating an electronic manual for use in the company you work for; perhaps you are an educator and are creating an electronic textbook for your students. In such cases your user-base is right at hand: you can copy your work to one or more floppy disks and sell it or give it away as you see fit. If user-response is enthusiastic you may see an opportunity for more ambitious distribution through a major publisher. Why not? If your work is useful and exciting for a number of people in one company, or in one department of one university, think of how great the market could be on a country-wide scale. Even if you don't have a ready-made user-base, there are two highly effective and inexpensive ways in which you can broadcast your work, potentially throughout the world. I use the term "broadcast" for good 41 reason. With both methods, you are ensured that thousands or perhaps millions of people will be made aware of the existence of your work: they will see its title and at least a brief description of it. Of those thousands or millions, some hundreds or thousands will choose to acquire a copy and spend some time with it. And of those, if you specify a registration fee, some portion of users may send you a check. When you ask for a registration fee you are distributing your work as shareware; when you don't, you're distributing it as freeware or are "putting it in the public domain". Always state up front what you are doing and what you expect from the user in return, if anything. For an electronic book, a reasonable shareware fee would be $5 to $10. (Many authors and programmers give the user a choice, with a notice something like this: "Suggested registration: $5-$10".) Bear in mind that with a *printed* book selling at $10 in the bookstores, you would be lucky to get back $1 for each copy sold -- the rest going to the printer, the publisher, the distributor, and the owner of the bookstore. Whether you go the shareware route or are happy to place your work in the public domain, you should *say so* both in the README file and on the title screen of your work or shortly thereafter. The first "broadcast" method is to send your work on disk to shareware distributors. You can always find ads for these companies in computer magazines, and they are always looking for new software to add to their catalogs. Shareware distributors operate by selling shareware and public domain software on disk; the charge per disk is minimal (usually $4 or $5), and covers only the distributor's costs -- none of it comes back to you. The advantage is that you get free advertising in the distributor's catalog. Of the people who purchase your work in this way, some may be appreciative enough to send you a registration check if you suggest a reasonable fee. But before that can happen you need to convince the distributor that your submission will interest his customers. Prepare your submission disk carefully, making sure there are no missing files; you should definitely include a README file as well as a GO.BAT file. Then write an intelligent cover letter in which you describe the work, tell why it is unique and whom it should interest, state whether it is shareware or freeware, and mention any hardware requirements if graphics are used. The idea is not only to get the distributor interested, but to make it as easy as possible for him to put your disk in his repertoire and make an attractive catalog blurb. The second broadcast method is to go electronic and post your work on the public BBS's and commercial services. The advantage of this method is that once you upload your work to a BBS, other users can download it. Except when there are long-distance charges (or the hourly fees of commercial services), nobody pays anything up front. A vast number of people learn of the existence of your work and can examine it without having to buy a disk from a distributor. Best of all, you need only "seed" your work in a few strategic locations for it to disseminate rapidly to hundreds or thousands of BBS's around the world. 42 The only difference between distribution on disk and distribution by telephone (the BBS method) is that in the latter case you must upload your work in the form of one or more compressed files. The commonest compression format uses the .ZIP extension and is created by the PKZIP program from PKWare. (If you plan on using any such compression program for profit, be sure to read the documentation to see if you should pay a registration fee.) Other compression formats include LZH, ARC, ZOO, and so on. The same principles apply to this method as the others: make a coherent package of your work, with at least a README file, and when you post it on a BBS, enter an informative desciption. The Orpheus Reader Once you have composed and compiled your work in Orpheus Author (OH.EXE), the most important part of the Orpheus system becomes, of course, the Orpheus Reader (OHREAD.EXE). This is the interface between you and the public, the decisive factor that could persuade the waiting world that your electronic book is better than anything that can be found in print. You have a right to expect the Orpheus Reader to be as exciting, user-friendly, and bullet-proof as the best software on the market. In your own best interests, take the Reader for a serious test-drive. See if you can crash it. See if there's any feature that is difficult or unsatisfying to use, or one it ought to have that it doesn't. Drop me a line with your comments and suggestions. Should the Reader have a manual? You tell me. In my opinion your work will come across more effectively if the interface to it does not *need* a manual -- if we can push the user right into it and let him discover for himself how quickly he feels comfortable. That's what electronic publishing is all about. It's NOT about printed manuals, it's about keeping everything immediately available through the screen using online Help. It's about teaching people that they can find their own way, the very essence of hypertext. As you'll notice when you test the Orpheus Reader, the first time you use it a special screen pops up to say, "Welcome to the Orpheus Reader". This gives a brief overview of the program and how to use it. The next time you start the Reader this screen will not appear, but it remains available from the menu. (The Reader detects a first-time user by the absence of a configuration file; you should never put your own OHREAD.CFG in the distribution package.) As mentioned in earlier chapters, the Reader automatically detects whether a document uses 24-line or 25-line cards. In the latter case, since the titlebar is hidden, the Reader posts a brief message telling the user how to call up the titlebar and menu system (press <Esc> or click the right mouse button). 43 Cleaning Up Eventually, after finishing a book and getting it out into the world, you will want to remove the original version from your hard disk. My advice is to save it first onto floppy disks, just in case you want to revise it one day. An effective method would be to use a compression utility such as PKZIP to create one ZIP file for each storage directory, with an additional ZIP file to hold the Homecard and its LST and PRJ files. Read about "Files and Directories" in online Help to learn how Orpheus sets up the subdirectories for a project; with a little care you can direct PKZIP to conserve the subdirectory structure along with your hypertext cards. Alternately, you could use a backup utility to do the same thing. When you are truly ready to remove a project from your hard disk, first load it in OH.EXE, then open the Project Menu and select "Erase Project". Orpheus will get you to confirm your choice before doing anything. If you confirm that you really want to do it, Orpheus will delete all files in that project's storage directories, remove those directories, then delete the Homecard and various subsidiary files like the LST and PRJ files (for that project only). It will NOT touch your compiled files, nor will it touch any files in other projects' directories. While you could do all this yourself from the DOS prompt or with a file manager, Orpheus does it much faster. A worthy victim for "Erase Project" will be the tutorial project we've worked on together in the previous chapters. You may want to keep it around for a while so you can continue trying things out, but when you know you're done with it, get Orpheus to zap it for you. 44 --------------------------------------------------------------------------- CHAPTER 6 - SHAREWARE : REGISTERING ORPHEUS --------------------------------------------------------------------------- Topics in this chapter: Licence What You Get When You Register Site Licencing Sharing Orpheus A Note to Pioneers Orpheus is distributed as SHAREWARE. This means that you are welcome to evaluate the system for up to 30 days. If you wish to use it after that period, you must pay the registration fee of $49. To enable you to make a thorough evaluation of the power of Orpheus, this package includes the Orpheus Reader (OHREAD.EXE) and the ability to compile your work to see what it would look like to the end user. However, you may not in any way distribute such work with the Orpheus Reader until you have registered the software and received your licence from Hyperion Softword. Licence Registered users of Orpheus receive an unlimited licence to sell, give away, or in any other manner distribute their compiled works, royalty- free, with as many copies of the Orpheus Reader as they require. Terms are detailed in the Software Licence Agreement that accompanies the registered version. What You Get When You Register * First of all, you get a registered copy of the latest version of Orpheus on disk. * Second, you get a registration number that Orpheus will build right into your compiled works (in encoded form). This is your ultimate proof that those works are yours. (It will also serve as a "password" barring entry to anyone but you, should you ever need to decompile your work. A decompiler will become available in 1993.) * Third, you get continuing free support by any of the methods decribed on the "Orpheus Support" sheet accompanying your registered copy. * Fourth, you get the right to upgrade your software, usually for free (from our support BBS or any BBS with the latest version) or for a modest fee in the case of major upgrades. * Fifth, if you are or become an electronic publisher you get the right to an "incremental site licence" as discussed below. * And finally, you receive the following utilities: SNAPSHOT.EXE ...... captures *any* graphic screen so that you can link it into your hypertext. REGIT.EXE ......... when you get updates from BBS's, tells the new Orpheus you're a registered user. 45 To register this copy of Orpheus, complete the registration form in the REGISTER.DOC file and send payment to: Hyperion Softword 535 Duvernay Sherbooke, QC Canada J1L 1Y8 Site Licencing Site licences are available to corporate or other users requiring multiple copies of the authoring system. The following price schedule is given for example only and represents the prices current at the end of 1992. Prices WILL rise in mid-1993, so be sure to enquire first if you wish to purchase a site licence. - first copy: full price ($49 plus $3 s/h) - next 10 copies: $35 each - next 10 copies: $30 each - additional copies: negotiable If you are or become an electronic publisher, and are a registered user of Orpheus, you have the right to an "incremental site licence" permitting you to purchase additional copies of Orpheus at a cost comparable to the price schedule above. As an electronic publisher, you will increasingly find yourself working with authors who wish to write directly in Orpheus. It is in your own best interest to ensure that they use _registered_ copies of the system, since (a) this fosters a mentality that helps protect your own work from piracy, and (b) it helps Hyperion Softword continue to support and improve the software. The incremental site licence makes this easy. Let's suppose you start off by purchasing 1 copy of Orpheus. A little later you start talks with an author whose work you intend to publish, and who wants to write in Orpheus. Call Hyperion Softword at 1-819-566-6296 and ask for the current price of an additional copy according to the incremental site licence. I will check your registration card and give you the best price available; in the example above that would be $35. You can have that copy registered in your name and shipped to you, or registered in the author's name and shipped to the author. However, both the order and the payment MUST come from you, not from the author. Each time you make such a purchase I will note it on your registration card, so that after a certain number of copies (10 in the example above) the next one would be at an even better price. NOTE: the price you will be offered will be the current price within each price level, not whatever it may have been at the time of your first purchase. 46 Sharing Orpheus Part of the shareware ethic is that you are welcome to help others learn about Orpheus in the same way you did. If you downloaded Orpheus from a BBS, you are welcome to upload it to others. Be sure to upload the entire system exactly as you received it, complete and unmodified. The same caution applies if you purchased Orpheus on disk from a shareware distributor. Finally, please note that if you are a registered user of Orpheus, your *registered* copy of the software must NEVER be treated as shareware, since it is in fact slightly different and includes a number of utilities that are only available to registered users. If you would like a copy of the shareware version to pass on to your friends, let me know and I will gladly send you one on disk. A Note to Pioneers Orpheus is about enabling creativity. *Your* creative daring may lead you to conceive of innovations in hypertext that I haven't thought of. If you have a project in mind that Orpheus seems right for but cannot currently enable, give me a call and we'll talk about it. The feature you need may already be on the way; if not, your idea could well be the motive for a future upgrade. 47 ---------------------------------------------------------------------------- CHAPTER 7 - ORPHEUS UTILITIES ---------------------------------------------------------------------------- Topics in this chapter: REGIT.EXE SNAPSHOT.EXE [The Orpheus Utilities are bonus programs given to registered users of Orpheus. They are not required to make a thorough evaluation of the shareware version of the system.] Everything you can do in Orpheus is built right into the program. However, there are times when it's handy or even necessary to have a small separate program to perform some special task. The Orpheus Utilities will be a small collection of such programs. Currently the collection consists of just two utilities, but there are more on the drawingboard. REGIT.EXE REGIT.EXE is a program that serves a purpose even when it doesn't do anything; its role is to help Orpheus recognize you as a registered user, and to protect your finished work from intruders. First, the passive role: updates of Orpheus will regularly appear on BBS's around the continent, in the form of new shareware versions. Since these will often contain significant new features or improvements, you will probably want to acquire them. Go right ahead! Normally you will be able to install them right over your old Orpheus files, since your work in progress will still be compatible with the new version. (To be safe however, you should always check the README file before installing a new version of anything.) The presence of REGIT.EXE in your Orpheus directory will inform the new version that you are a registered user. If your OH.CFG file contains your registration number, the new version will recognize that too; if it does not, start up OH.EXE and press <Alt-H> to open the Help Menu, then select "Registration" and type in the number on your distribution disks. To make this very clear: once you are a registered user you can take advantage of shareware updates and compile all the books you want. To do this, you MUST have REGIT.EXE in your Orpheus directory, and your registration number MUST be showing on the Help Menu. Now for REGIT.EXE's active role: if you came to Orpheus through shareware, you may have compiled a book before receiving your registered copy. The shareware version of Orpheus is not in any way crippled or 48 restricted, but it does leave its mark on anything you compile with it. The Orpheus Reader recognizes such books as having been made with an unregistered copy, and says so. Moreover such books are missing an important ingredient: your encrypted registration number. When you compile a book with a registered copy of Orpheus, it hides an encrypted copy of your registration number right inside the book. This is the ultimate proof that you are the author of it; it is also something more. One of the programs that I plan to add to the Orpheus Utilities is a decompiler: a program that can take a compiled electronic book and unfold it into its original state as cards. But if *you* can decompile an Orpheus book, can't everyone else who has a registered copy? NO. The decompiler will check your registration number, compare it with the encrypted version in the book you want to open, and proceed only if the two match. Of course, we could have used a password system, but then you would have to remember where you wrote the password. With this system you can't go wrong: your registration number is on the label of your distribution disks, AND here in the user files at Hyperion Softword. Where does REGIT.EXE fit into this? If you have compiled a book with the shareware version and deleted the original, REGIT.EXE can update your compiled book, complete with encrypted registration. The result is exactly the same as if you had compiled it with the registered version. STEP 1: begin by installing your registered copy of Orpheus in your usual Orpheus directory. Start up OH.EXE and press <Alt-H> to open the Help Menu, then <R> to select "Registration #". Type in the number given on the label of your distribution disks, and press <Enter>. Orpheus immediately writes a new copy of your personal configuration file (OH.CFG) to disk, complete with your registration number. STEP 2: exit Orpheus and check whether your compiled book is in your Orpheus directory (along with REGIT.EXE and OH.CFG). If it is not, copy your book's HTX file into the Orpheus directory before continuing; REGIT.EXE only concerns itself with HTX files. Now give the "REGIT" command at the DOS prompt, and if all goes well you should see a report of the results: how many files found, how many updated, how many were already registered. (If REGIT.EXE encounters an HTX file compiled with a registered copy of Orpheus, it leaves it alone.) Of course, the other way to update your work is simply to recompile it with your registered copy of OH.EXE. With an exceptionally long book you may not want to do that. 49 SNAPSHOT.EXE SNAPSHOT.EXE is a utility developed by Ted Gruber Software as part of Fastgraph, the professional graphics library used in Orpheus. Hyperion Softword is licensed to distribute Snapshot with those of its products that employ the Fastgraph library. Registered users of Orpheus can use Snapshot to capture graphics for their hypertext books. Snapshot is a TSR; this means that once you load it, it remains in the background even after returning control to DOS so that you can run other programs. Later, if you press the Snapshot hotkeys while in a graphics program, Snapshot comes alive long enough to capture the graphics screen to a disk file in the SPR format. Snapshot then returns control to the graphics program, allowing you to view and capture other images if you wish. (Note that once loaded, Snapshot remains in memory until you reboot your computer. If you use the MARK/RELEASE or similar utilities you can give a MARK command before loading Snapshot, then a RELEASE command when you no longer need it. If you use Desqview and your windows are large enough, load Snapshot in the window where you will load the graphics program, then close the window when done.) **** Do NOT load Snapshot or any other TSR from within a shell. **** Here's how to load Snapshot. At the DOS prompt, give the SNAPSHOT command and press <Enter>. If it loads successfully, Snapshot will identify itself and remind you to press <Alt-Left Shift> to activate it. Now you are at the DOS prompt again, so you can load your paint program or graphics viewer. While doing so, note the screen resolution the program will be using; some paint programs let you choose the resolution from a menu, while others let you set the resolution on the command line or in a startup batch file. Consult the appropriate manual if you aren't sure. With the graphics program running, load an image that you would like to capture. If you are using a paint program, part of the screen may be taken up by menu lines and toolbars; select the command that temporarily removes these to let you see your entire graphic taking up the full screen. Once your graphic is displayed in full-screen form, press the Snapshot hotkeys: that is, press and hold down the <Alt> key, add the <Left Shift> key, then release both keys. If Snapshot successfully captures the screen it will announce this with three quick tones of medium pitch. If it is not successful it will give a single low-pitched tone; this also happens if you press the hotkeys while in text mode. Since Snapshot remains in memory until you reboot or otherwise remove it, you can go on to view and capture other graphics if you wish, all without reloading Snapshot from the DOS prompt. But let's assume for now that you only wanted to capture the one image, and have exited your graphics program. The next task is to locate the capture file and bring it into Orpheus. 50 After exiting the graphics program give the following command at the DOS prompt: "DIR SNAPSHOT.*" <Enter>. If you captured only one image there will be only one file: SNAPSHOT.000. If you captured two, the second will be named SNAPSHOT.001. Snapshot will save up to a thousand images in the current directory, numbering them from 000 to 999. When saving a new image it uses the lowest available number, so if you save 10 images and then delete the first, the next image will be numbered 000. If you plan on saving more than one image, make a list of them as you go along, with a brief description of what each one shows. The next step is to rename your SNAPSHOT.nnn file, both for your own convenience and so that Orpheus will recognize it. The first part of the name (up to 8 letters) should refer to the contents of the image, to help you remember what it is. The second part of the name, the three-letter extension after the dot, must be "SPR"; this tells Orpheus that the file is an image in Fastgraph's Standard Pixel Run format. For example, suppose your image is a painting of the Grand Canyon, and that you saved it into SNAPSHOT.000. To rename it, you would give the following command at the DOS prompt: "RENAME SNAPSHOT.000 CANYON.SPR". Orpheus looks for graphics and ansi files in the current directory, and if it doesn't find them, looks next in the location specified with the ORPHEUS environment variable -- if you have set it. For more information read Appendix C, "Using the ORPHEUS Environment Variable". Before you can display a graphic in Orpheus you must place a copy of the file in one of those locations. The last step is to start up Orpheus, create or navigate to the desired Graphic card, and type in a valid graphic() command as described in Part II of the User's Guide. Remember that for SPR and PPR files, *unless* you are using a full-screen image, the graphic() command requires that you give a little thought to the numbers you enter as the fourth and fifth parameters. The fourth parameter represents the pixel-row of the lower left corner (as opposed to the upper left corner in PCX files). The fifth parameter represents the image width in pixels and must be entered (whereas for PCX images it can be given as 0). 51 --------------------------------------------------------------------------- APPENDIX A - ORPHEUS AND OTHER SOFTWARE --------------------------------------------------------------------------- Disk Caches You can safely use Orpheus with a disk cache provided your setup does NOT include a write delay. Experts know that a write delay of even a second is far too risky to justify the tiny increase in performance. Orpheus occasionally updates a large number of files at high speed; if an error occurs, Orpheus needs to know immediately, not a second later. Desqview If you are a Desqview-user, you may be interested in the following setup parameters for giving Orpheus its own window. On the main "Change a program" screen, use the following parameters: Memory size (in K): 512 Writes directly to screen: Y Displays graphics information: Y Virtualize text/graphics: N Uses serial ports: N Requires floppy diskette: N To set the following more specific parameters, press <F1> to open the advanced options screen. Use the following parameters: Text pages: 4 Graphics pages: 2 Uses its own colors: Y Uses math coprocessor: N Window position: Maximum height: 25 Maximum width: 80 Runs in background: N Other options can be left at their default values. For optimum performance you should set the following parameters: Keyboard conflict: 4 Protection level: 0 Note that if you do not EVER plan to use graphics in Orpheus, you can change "Displays graphics information" to "N", and "Graphics pages" to "0". If using a monochrome monitor (NOT one with 16 shades of grey etc.), you can change "Text pages" to 1. The same settings can be used for both the Orpheus Author (OH.EXE) and the Orpheus Reader (OHREAD.EXE), although the Reader uses much less memory than does the authoring program. 52 --------------------------------------------------------------------------- APPENDIX B - USING ORPHEUS ON A NETWORK --------------------------------------------------------------------------- As of version 1.22, the Orpheus Reader is network-friendly: users may access book files anywhere on the system while keeping their "personal" files in their own directories. The following rules apply: 1. OHREAD.HLP (the help file) must be in the same location as the Reader itself, OHREAD.EXE. 2. All of the files in a book (including any graphics) must be in the same location, which can be different from the above. 3. The user's personal configuration file, OHREAD.CFG, along with optional notepad and bookmark files (named after a given book but with NPD and BMK extensions) will be saved to disk in the user's current directory, which can be different from the two locations above. There is one exception to rule 2. If you use the RUN or RUNBAT commands in an Action card, and if the command line includes a path, that path is preserved in the compiled book. (This is not the case with graphics, where the path is stripped during compilation.) Here are some examples of command lines with which the Orpheus Reader would load a book named NETNEWS.HTX: ...with all files together, or the Reader in a pathed location: OHREAD NETNEWS.HTX ...with the book in a different directory on drive d: OHREAD D:\DIFF_DIR\NETNEWS.HTX ...with the book as above and the Reader in a non-pathed location: C:\STUFF\OHREAD D:\DIFF_DIR\NETNEWS.HTX Two users on a network could give the last command, for example, and read Netnews simultaneously. Their personal CFG, NPD and BMK files would be saved in their own directories without conflict. In a future version, Orpheus may permit network users to identify their personal CFG, NPD and BMK files by the users' initials, and to store those files in a public directory. In the meantime, if you are providing Orphic documentation on a network you should warn your users NOT to call the Reader while in a public directory, but to do so only while in their own directories. This will prevent conflicts in the use of files like OHREAD.CFG. 53 --------------------------------------------------------------------------- APPENDIX C - USING THE "ORPHEUS" ENVIRONMENT VARIABLE --------------------------------------------------------------------------- With Version 1.30 Orpheus introduced the ability for you to give the program certain setup information using an environment variable. Currently this is limited to telling Orpheus where to look for graphic files (including ansi screens); we'll add other capabilities later. Both OH.EXE and the Orpheus Reader now check for this environment variable if they are unable to find a graphic or ansi file where it was expected. Environment variables may be set from within batch files or at the DOS prompt. If you are unfamiliar with this technique, consult your DOS manual regarding the SET command. To tell Orpheus where to look for graphic and ansi files, use the ORPHEUS environment variable together with a "/G" switch. For example, suppose your graphic images are all stored on drive C: in a directory named ART. You would use the following line in a batch file or as a command given directly at the DOS prompt: SET ORPHEUS=/GC:\ART If your images were stored on drive D: in a subdirectory named PAINT\IMG, the line would be: SET ORPHEUS=/GD:\PAINT\IMG Once you have created an environment variable (which takes up a small amount of RAM), you can remove it from memory by giving the SET command with no data after the "=" sign, like so: SET ORPHEUS= This would remove the ORPHEUS environment variable from memory. 54 --------------------------------------------------------------------------- APPENDIX D - FORMAT OF AN UNCOMPILED CARD --------------------------------------------------------------------------- Topics in this Appendix: Structure of a Card Number Systems The Filename Header and Link Codes The Header Linkwords This Appendix is for the use of technically-minded users who are comfortable with control codes and number systems, and who possess the software utilities to let them view and optionally edit the contents of partially-binary files. The information below can be used to repair a card that has been damaged through user-error, a bug, or other misfortune. The only way to see the "real" contents of an uncompiled card is to use a file-viewer that is capable of hexadecimal display. A good example is Vern Buerg's LIST.COM: load a card in LIST and then press Alt-H to switch to hex mode. This shows you every single byte in the file. Most word processors are *not* capable of editing Orpheus files, but many text editors are. Note that cards made after version 1.23 may appear to be on a single line. I have successfully edited damaged cards using PC-Write and Multi-Edit. The first time you attempt any such procedure, you should of course save a copy of the card in case you make a mistake and don't know how to recover. Structure of a Card Uncompiled cards consist of three parts: a filename, a header, and the text. The filename bears a card's link-number and is thus crucial. The header tells what kind of file and what kind of card it is, plus other information such as the link-number of its parent card. The text may include embedded codes for linking. Note that line-endings are represented with a single linefeed character, ascii 10 (0Ah), rather than the traditional CR/LF pair (ascii 13/10 or 0Dh/0Ah). Number Systems I use 5 number systems in working with Orpheus: base-2, base-10, base-16, base-36, and base-200. For most of this Appendix you only need two: the familiar decimal (base-10), and hexadecimal (base-16). Decimal counting is useful when you need to insert a control-code or other non-alphabetical character; if you know the character's ascii value you just hold down the Alt key, type the numbers in decimal using 55 the Number Keypad, then release the Alt key. For other purposes it is more useful to use hex, particularly since you can only see the real contents of a file using hex display. Whenever I give hexadecimal values I will do so like this: "0Ah". Hex digits are 0123456789ABCDEF, so 0Ah means 10 decimal, 0Fh means 15 decimal, and 10h means 16 decimal. Orpheus uses two special number systems for identifying link-numbers. To allow a document to contain up to 32000 cards, we require a method of representing such numbers in as few digits as possible. With base-10 notation you need 5 digits, with the maximum value being 99999. With base-36 notation you need 3 digits, with the maximum value being 46655. With base-200 notation you need just 2 digits, with the maximum value being 39999. Obviously the last two are more efficient. Accordingly, we use base-36 notation in filenames, placing the link number in the three characters of the file extension. But inside cards we use base-200 notation to represent link numbers in only 2 characters. If there is ever a need to expand capacity to, say, a few million cards, this could be accomplished with a relatively minor change to the system. You should not EVER need to convert link numbers from one notation to another, but I'm going to explain them anyway. Base-36 notation uses the 10 numeric characters from 0 to 9, followed by the 25 alphabetic characters from A to Z. Reserving link number 0 for the Homecard, a file extension of .000 represents link number 1, .00Z represents number 36, .010 represents number 37, .01Z represents number 72, and .020 represents number 73. Base-36 notation is ONLY used in filenames. (To find the decimal version of a card's number, just open the File Menu: it's there beside the "Save As" command.) Base-200 notation uses the sequence of 200 ascii values starting from the "!" character, which has a value of 33 (21h), and extending to the character with a value of 232 (E8h). The sequence !"#$ is equivalent to 0123 (in terms of their ascii values minus 33), and therefore we can interpret our 2-character link codes as follows: again reserving 0 for the Homecard, !! represents link number 1, !" represents link number 2, !# represents link number 3, "! represents link number 201, #! represents link number 401, and $# represents link number 603. Base-200 notation is ONLY used inside uncompiled cards. You will surely agree that before fiddling with anything except the text in an uncompiled card, you should know what you're doing. Link numbers are intended to be handled internally by Orpheus, NOT by human hands; they are therefore designed for optimal speed and efficiency as used by the program, rather than for the convenience of hackers. The Filename Since the filename contains the link number of a card, it is in some ways the most crucial ingredient. If you change the filename carelessly you can severe the tie connecting the card to the rest of your document. The significant part of the filename is the 3-letter extension, which as 56 described above represents a link number in base-36 notation. The link number also tells Orpheus where to store and retrieve a file. Storage directories contain up to 100 files each following a strict sequence: \D1 holds files 1-100, \D2 holds files 101-200, and so forth. This means that if Orpheus is looking for card 156 it will ONLY look in the \D2 directory, nowhere else. If you do happen to rename a file manually, be sure to figure out what directory to put it in. The root part of the filename is relatively insignificant, with one exception. When a card is orphaned (unlinked but not deleted), Orpheus changes the last character of the root part to a curly brace, "{". When you open the Recover Orphan dialog, Orpheus looks for cards with that distinguishing mark in the filename. The rest of the root part is designed to make it easier for you to identify cards either in the Recover dialog or if you should ever need to do things manually. With Doors and Notes, as well as Action and Graphic cards, the root part of the filename is derived from the original linkword, with any characters that DOS does not permit in a filename being replaced by others that are (such as an underscore for a space). With Inits and More links the words "init" and "more" are used. Header and Link Codes The following codes are used in the file header and as link codes embedded in the text. Some are no longer in use as of version 1.30. orpheus-code 236 (ECh) nodetype-code 30 (1Eh) uncompiled-code 8 (08h) projectdir-code 7 (07h) homelink-code 25 (19h) childlink-code 24 (18h) interlink-code 18 (12h) - no longer used internote-code 21 (15h) - no longer used more-code 26 (1Ah) uplink-code 23 (17h) lock-code 76 (4Ch) keyname-code 1 (01h) - no longer used headend-code 31 (1Fh) door-code 22 (16h) - prior to V1.24 was 11 (0Bh) note-code 19 (13h) graphic-code 1 (01h) - prior to V1.24 was 2 (02h) action-code 23 (17h) - prior to V1.24 was 3 (03h) init-code 73 (49h) crosslink-code 29 (1Dh) downlink-code 18 (12h) - prior to V1.24 was 14 (0Eh) 57 The Header Every Orpheus file, with the sole exception of Notepad (NPD) files, begins with a 3-byte pre-header consisting of orpheus-code (ECh), a version code, and a filetype code. The version code is for internal use and is NOT identical to the Version number given on your disk labels or in the About or Version windows. The very first version code used was 16 (10h), seen only in Version 1.0 (August 1992). Subsequently numbering went back to 2, and as of Version 1.50 (March 1993) was up to 5. This number changes whenever new features are implemented that are incompatible with old versions -- particularly old versions of the Orpheus Reader. OH.EXE also uses the number to detect cards that use old codes or CR/LF pairs instead of a single linefeed. OH.EXE maintains backward comptability with uncompiled cards created with earlier releases. The Orpheus Reader does NOT maintain backward compatibility with compiled books created with earlier releases. To continue, the header of an uncompiled card consists of the following: 236 (ECh) - orpheus-code - - a 1-byte version code 8 (08h) - uncompiled-code - - a 1-byte counter giving the total length of the header - - - - a data sandwich consisting of codes, data, and spaces - - 31 (1Fh) - headend-code to back up the length counter In no particular order, the data sandwich has the following layers: * 30 (1Eh) - nodetype-code, with: - - a 1-byte code for what type of card it is, such as homelink-code, childlink-code, etc. 32 (20h) - a space * 26 (1Ah) - more-code (ONLY IF the card has a More link), with: - - 2 bytes for the linked card's number in base-200 - 32 (20h) - space * 73 (49h) - init-code (ONLY IF the card has an Init link), with: - - 2 bytes for the linked card's number in base-200 - 32 (20) - space * 23 (17h) - uplink-code (ONLY IF it isn't the Homecard), with: - - 2 bytes for the parent card's number in base-200, - OR homelink-code twice if the parent is the Homecard 32 (20h) - space 58 * 7 (07h) - projectdir-code (ONLY IF this is the Homecard, with: - - an indeterminate number of bytes giving the name - of the project directory for this document 32 (20h) - space * 76 (4Ch) - lock-code (ONLY IF this card is "locked" to prevent accidental autoreformat) 32 (20h) - space * 1 (01h) - keyname-code (ONLY in versions prior to 1.30), with: - - a phrase for use with the map (no longer used) 1 (01h) - another keyname-code to flag the end 32 (20h) - space Linkwords Linkwords are preceded by a 1-byte code that signifies both the beginning of a linkword and the link type. This code can be: door-code, note-code, crosslink-code, graphic-code, or action-code. The end of a linkword is indicated by downlink-code, which is then followed by 2 bytes giving the number of the linked card in base-200 notation, with ascii 33 representing 1. A linkword and all of its codes must be on a single line. 59