home *** CD-ROM | disk | FTP | other *** search
/ Zodiac Super OZ / MEDIADEPOT.ISO / FILES / 21 / OH211A.ZIP / MANUAL.TXT < prev    next >
Text File  |  1996-07-17  |  73KB  |  1,561 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                                     ORPHEUS
  9.  
  10.  
  11.  
  12.                         An Integrated Development Suite
  13.  
  14.                             For Hypertext Authoring
  15.  
  16.  
  17.  
  18.                                 - User's Guide -
  19.  
  20.  
  21.  
  22.  
  23.                         Copyright 1996 Hyperion Softword
  24.  
  25.  
  26.  
  27.  
  28.     Orpheus is a suite of programs dedicated to the creation and distribution
  29.     of hypertext.  The main program, OH.EXE, provides an integrated platform
  30.     for hypertext authoring.  The runtime reader, OHREAD.EXE, is distributed
  31.     to end-users with works in finished forms.  Among the other components,
  32.     OH1to2.EXE is a conversion program for use by authors wishing to upgrade
  33.     from Orpheus 1.
  34.  
  35.     Orpheus makes you a master of hypertext; it gives you the freedom to
  36.     explore the multiple dimensions of your subject while bringing them
  37.     within easy access of your readers; it gives you the flexibility to
  38.     experiment, to revise and restructure at will; it gives you the power to
  39.     compose spontaneously in an electronic galaxy, then to release the worlds
  40.     you have created so that others may experience them.
  41.  
  42.     Orpheus is SHAREWARE.  This means that you are welcome to evaluate the
  43.     system, but you may not distribute anything you might create with it
  44.     without purchasing a registered copy.  For pricing and a handy order
  45.     form, please see the file REGISTER.TXT.
  46.  
  47.                                Hyperion Softword
  48.                                535 Irene-Couture
  49.                                Sherbrooke, QC
  50.                                Canada J1L 1Y8
  51.  
  52.                                Tel/fax: 819-566-6296
  53.                                Email: willmot@interlinx.qc.ca
  54.  
  55.  
  56.  
  57.  
  58.  
  59.                                        1
  60.  
  61.  
  62.  
  63.  
  64.     ACKNOWLEDGEMENTS:
  65.  
  66.     Warm thanks to the beta testers who have contributed to the story
  67.     so far:  Ray Ballard, Andy Roberts, Wim Berden and the guys at ILS,
  68.     Joost van der Gaag.
  69.  
  70.     Thanks in many tongues to all those who have worked on translations
  71.     of the Orpheus Reader:  Daniel Marois, Marc Coulombe, Jan Moens,
  72.     Jurgen Nijhuis, Paul de Kamp, Thorsten Glattki, Giovanni Calesini,
  73.     Jesus de Paula Assis, Ernesto Eduardo Casin, Alexander E. Gubin.
  74.  
  75.     Orpheus uses the SPAWNO routines by Ralf Brown to minimize memory
  76.     use while shelling to DOS and running other programs.
  77.  
  78.  
  79.     CONVENTIONS FOLLOWED IN THIS MANUAL:
  80.  
  81.     Keystrokes are indicated by <> brackets; for example, <F1> means press and
  82.     release the F1 key, <H> means press and release the "h" key.  Combination
  83.     keystrokes are hyphenated; for example, <Alt-F> means press and hold down
  84.     the Alt key, then press the "f" key, then release both keys.
  85.  
  86.     The term "Orpheus" is used both in reference to the system as a whole
  87.     and to its main component, OH.EXE (the authoring program).  Other
  88.     components are referred to with names related to their function, such as:
  89.     the Reader (OHREAD.EXE), Help (OHHELP.EXE), the Simulator (OHSIM.EXE),
  90.     the Indexer (OHINDEX.EXE), and the Converter (OH1to2.EXE).
  91.  
  92.     TRADEMARKS
  93.  
  94.     Trademarks are the property of their respective holders.
  95.  
  96.  
  97.  
  98.  
  99.  
  100.  
  101.  
  102.  
  103.  
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.                                       2
  120.  
  121.  
  122.  
  123.  
  124.   ---------------------------------------------------------------------------
  125.                         T A B L E  O F  C O N T E N T S
  126.   ---------------------------------------------------------------------------
  127.  
  128.  
  129.  
  130.  Chapter 1  -  Getting Started ......................................... 4
  131.     Quickstart ......................................................... 4
  132.     How To Use This Manual ............................................. 4
  133.     Printing This Manual ............................................... 4
  134.     System Requirements ................................................ 5
  135.     Installation ....................................................... 5
  136.     Upgrading from Orpheus 1 ........................................... 5
  137.     Getting Help ....................................................... 6
  138.  
  139.  Chapter 2  -  The Orpheus Environment ................................. 7
  140.     The Editor ......................................................... 7
  141.     Statusbar .......................................................... 8
  142.     Using Menus ........................................................ 9
  143.     Using Help ......................................................... 10
  144.     Using Dialogs ...................................................... 10
  145.     Customizing Orpheus ................................................ 11
  146.  
  147.  Chapter 3  -  Tutorial : a Hypertext Project .......................... 15
  148.     What is a Project? ................................................. 15
  149.     How Do You Develop a Project? ...................................... 17
  150.     Starting a New Project ............................................. 17
  151.     Expanding a Project ................................................ 19
  152.     Importing Text ..................................................... 20
  153.     Navigating Hypertext in OH.EXE ..................................... 22
  154.     What's in a Card? .................................................. 23
  155.     Finishing a Project ................................................ 24
  156.  
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.                                       3
  180.  
  181.  
  182.  
  183.  
  184.   ---------------------------------------------------------------------------
  185.                          CHAPTER 1  -  GETTING STARTED
  186.   ---------------------------------------------------------------------------
  187.  
  188.  
  189.  
  190.  Topics in this chapter:  Quickstart
  191.                           How To Use This Manual
  192.                           Printing This Manual
  193.                           System Requirements
  194.                           Installation
  195.                           Upgrading from Orpheus 1
  196.                           Getting Help
  197.  
  198.  
  199.  
  200.  Quickstart
  201.  
  202.        If you're the intrepid explorer type who never reads manuals, go ahead
  203.     and fire up the authoring program (OH.EXE).  Everything you need to know
  204.     is in the menus and online Help.  Browse them both, experiment, have fun.
  205.     For an explanation of any menu item, click on it with the right mouse
  206.     button or place the selection bar on it and press <F1>.  To make sure you
  207.     get off on the right foot, I suggest you read Chapter 3, the tutorial on
  208.     making hypertext with Orpheus.
  209.  
  210.  
  211.  How To Use This Manual
  212.  
  213.         This manual is a supplement to OH.EXE's online Help.  Use it to find
  214.     out what Orpheus is all about, to get set up, to take your first steps on
  215.     the path of hypertext authoring.  Bear in mind however that all of the
  216.     detailed information on Orpheus IS in online Help, which you can open
  217.     at any time in OH.EXE by pressing <F1>.  You can also run Orpheus Help as
  218.     a standalone program:  give the command OHHELP at the DOS prompt.
  219.  
  220.  
  221.  Printing This Manual
  222.  
  223.         If you have Microsoft Write (and if you have Windows, you certainly
  224.     do), load the MANUAL.WRI version of this document in Write and print it
  225.     from there.  This will give you the best output.
  226.  
  227.         Otherwise... set your printer to 6 lines per inch, 12 characters per
  228.     inch, and use the following command at the DOS prompt:
  229.  
  230.                 COPY MANUAL.TXT PRN
  231.  
  232.     Alternately you can load this file into your favorite word processor,
  233.     and format and print it however you wish.  There are 59 lines per page,
  234.     with the last line of text at line 55.
  235.  
  236.  
  237.  
  238.  
  239.                                       4
  240.  
  241.  
  242.  
  243.  
  244.  System Requirements
  245.  
  246.        The authoring program (OH.EXE) requires 512K of RAM, DOS 3.2 or higher,
  247.     and a hard disk.  There are no particular video requirements unless you
  248.     wish to display graphics.  For best performance with large projects, XMS
  249.     memory is recommended but not required.
  250.  
  251.        The Orpheus Reader (OHREAD.EXE) requires 340K or more of RAM, depending
  252.     on the work being displayed, and DOS 3.2 or higher; a hard disk is NOT
  253.     required.  Video requirements depend on the graphical demands, if any,
  254.     of the work being displayed.
  255.  
  256.         All Orpheus programs should run on any IBM-compatible computer, from
  257.     the late-model XT through AT, 386, 486, and Pentium systems.  Orpheus will
  258.     not run on the PCjr or early XT's.  All Orpheus programs run happily
  259.     under Windows or OS/2.  A Microsoft-compatible mouse is required for
  260.     drawing hotspots in graphics.
  261.  
  262.  
  263.  Installation
  264.  
  265.         Orpheus should be installed in its own subdirectory on your hard
  266.     disk, such as "C:\OH2".  You will need at least 1.4 megabytes of free
  267.     disk space.  If installing from disks received from Hyperion Softword,
  268.     follow the instructions that came with the disks.  If installing from
  269.     compressed files downloaded from the Internet or a BBS, create an
  270.     Orpheus directory and uncompress them into that directory.
  271.  
  272.         Orpheus 1 and Interim Version users:  If you have used Orpheus 1 or
  273.     the Interim Version, be sure to install Orpheus 2 in a completely different
  274.     directory.  The only contact between Orpheus 2 and earlier versions should
  275.     be via the Converter, OH1TO2.EXE (see below, "Upgrading from Orpheus 1").
  276.  
  277.         Orpheus requires that the DOS "Files" variable be set to at least
  278.     15.  If your system runs Windows or OS/2 this is guaranteed to be the
  279.     case.  If not, look in your CONFIG.SYS file (in the root directory of your
  280.     hard disk) for the line beginning "FILES=".  Make sure that the number
  281.     given is at least 15; if you change it, reboot the computer to make the
  282.     new setting come into effect.
  283.  
  284.         Once Orpheus is installed you can work with it in other drives or
  285.     directories, if you wish, provided you either specify a path on the
  286.     command line or include the Orpheus directory in the PATH environment
  287.     string given in your AUTOEXEC.BAT file.  If you don't have an AUTOEXEC.BAT
  288.     file, or don't know how to use the PATH command, consult your DOS manual.
  289.  
  290.  
  291.  Upgrading from Orpheus 1
  292.  
  293.         If you have projects developed with Orpheus 1.nn or the Interim
  294.     Version, you can use the Converter (OH1TO2.EXE) to upgrade them to
  295.     work with Orpheus 2.  See OH1TO2.TXT for details.
  296.  
  297.  
  298.  
  299.                                        5
  300.  
  301.  
  302.  
  303.  
  304.  Getting Help
  305.  
  306.         If you get stuck or need something explained, the FIRST thing to do
  307.     is to explore online Help.  In virtually all situations, pressing <F1>
  308.     calls up context-sensitive Help with an explanation of what you need to
  309.     do or know.  When menus are open, context-sensitive Help on any item
  310.     can be had by clicking on it with the right mouse button; or move the
  311.     selection bar to that item and press <F1>.  You can also run Orpheus Help
  312.     as a separate program, by giving the command OHHELP at the DOS prompt.
  313.  
  314.         If you're still stuck (and have already absorbed this manual), you
  315.     are welcome to contact me (Rod Willmot) at Hyperion Softword, by one of
  316.     the following methods:
  317.  
  318.     (1) Email (willmot@interlinx.qc.ca) -- this is the best way to get help,
  319.         report problems, or discuss improvements you'd like to see.
  320.     (1) Call or fax 1-819-566-6296, preferably between 11:00 a.m. and 11:30
  321.         p.m., New York time (generally 7 days a week).  I can help best if
  322.         your computer is up and running with Orpheus loaded.
  323.     (3) Write to me at Hyperion Softword, 535 Irene-Couture, Sherbrooke, QC,
  324.         Canada J1L 1Y8.  This is the worst way to get help because the
  325.         turnaround time for me to receive and reply to your letter is simply
  326.         too long.
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.  
  339.  
  340.  
  341.  
  342.  
  343.  
  344.  
  345.  
  346.  
  347.  
  348.  
  349.  
  350.  
  351.  
  352.  
  353.  
  354.  
  355.  
  356.  
  357.  
  358.  
  359.                                        6
  360.  
  361.  
  362.  
  363.  
  364.   ---------------------------------------------------------------------------
  365.                     CHAPTER 2  -  THE ORPHEUS ENVIRONMENT
  366.   ---------------------------------------------------------------------------
  367.  
  368.  
  369.  
  370.  Topics in this chapter:  The Editor
  371.                           Statusbar
  372.                           Using Menus
  373.                           Using Help
  374.                           Using Dialogs
  375.                           Customizing Orpheus
  376.  
  377.  
  378.  
  379.         Orpheus (OH.EXE) is an Integrated Development Environment for
  380.     creating hypertext documents.  Everything you need to compose, revise,
  381.     and enhance such documents is right at your fingertips.  In this chapter
  382.     we'll take a look at that environment and how you can expect to use it.
  383.  
  384.  
  385.  The Editor
  386.  
  387.         When you start up OH.EXE the first time, you will see an empty
  388.     screen with a statusbar at the top and the cursor in the upper left
  389.     corner.  What you are looking at is a full-screen window in the
  390.     hypertext editor that is at the heart of Orpheus.  You can open 9 such
  391.     windows.  As shown by the "1" on the statusbar (beside "Esc:Menu"), you
  392.     start off in Edit window 1.
  393.  
  394.         In Orpheus 2, uncompiled hypertext cards are simply text files,
  395.     combining the words you want your readers to see with codes for
  396.     hypertext links.  Since the codes themselves are text, you could use
  397.     just about any editor to compose an Orpheus project.  The advantage of
  398.     OH.EXE's editor is that, except when you actually want to see the codes,
  399.     it interprets and hides them, letting you see your work the way your
  400.     readers will see it, and navigate through it as hypertext even while
  401.     you are still writing it.
  402.  
  403.         As you work on a project in Orpheus, you will typically have from
  404.     half to all 9 possible Edit windows open, some containing various parts
  405.     of your project, others perhaps containing external text files that you
  406.     are using as resources.  (Besides composing hypertext, the Edit windows
  407.     can be used to view or edit text files not belonging to a project.)
  408.     When you exit OH.EXE or switch to a different project, Orpheus saves
  409.     a record of the window contents for the project you were working on.
  410.     The next time you open that project, Orpheus will restore the windows
  411.     to what they contained before you quit.
  412.  
  413.         For more about the Edit windows in Orpheus, check out the Window
  414.     Menu and read online Help.
  415.  
  416.  
  417.  
  418.  
  419.                                       7
  420.  
  421.  
  422.  
  423.  
  424.  Statusbar
  425.  
  426.         The Statusbar displays a variety of messages and symbols that keep
  427.     you informed of where you are and what you are doing; some of them can
  428.     be used with the mouse to switch windows, toggle edit modes, or navigate
  429.     hypertext.  The illustration below represents all of the items that might
  430.     appear.  (See online Help for more thorough discussions of each.)
  431.  
  432. Esc:Menu |*1 | Push Marking IniExiPrvNxtRptMor Wrap | ∞ |[   1]| "FILENAME.EXT"
  433. 1         2    4    5       6  7  8  9  10 11  12     13 14   16 17
  434.            ^3                                                ^15
  435.  
  436.     (1) Press <Esc> to open the menu system, or click on "Esc:Menu".  To
  437.     open a specific menu in one step, press <Alt> with the first letter of
  438.     the name of the menu, e.g. <Alt-F> for the File Menu.
  439.  
  440.     (2) A hilited asterisk indicates that the file in the current window
  441.     has been changed since it was last saved to disk.
  442.  
  443.     (3) Item 3 is the number of the current Edit window being displayed.
  444.     If you click on this number Orpheus switches to the next non-hidden
  445.     window if any.  For other window-related commands, open the Window Menu.
  446.  
  447.     (4) The current editing mode is indicated here:  "Push" for Pushright
  448.     means that typing a character pushes any existing text at the cursor to
  449.     the right; the opposite is "Over" for Overwrite.  Press <Ins> to toggle
  450.     from one mode to the other, or use the Edit Menu.
  451.  
  452.     (5) Next comes a message area, which is normally blank.  The illustration
  453.     displays the "Marking" message, which would appear if you were marking a
  454.     block of text.  If you click on this area (whether blank or not), the
  455.     Mouse Blocks dialog opens to facilitate block operations with the mouse.
  456.  
  457.     (6-11) The central area of the Statusbar is reserved for flags that
  458.     indicate whether the current card has a certain type of built-in link.
  459.     These are:  "Ini" for an Init link, "Exi" for an Exit link, "Prv" for
  460.     a Prev link, "Nxt" for a Next link, "Rpt" for a Report link, and "Mor"
  461.     for a More link.  To navigate such a link you can click on the flag or
  462.     go use the Link Menu.  Note that the Reader interface to such links is
  463.     completely different; for example, Init and Exit links are events that
  464.     the Reader performs automatically when the user enters or leaves a card
  465.     with such links.
  466.  
  467.     (12) Another edit-mode toggle concerns wordwrap and autoreformat.  "Wrap"
  468.     means that wordwrap is active; "Rfmt" means that autoreformat is active.
  469.     You can toggle these states either by clicking on the flag, or through the
  470.     Edit Menu.  In ascii mode (see next) wordwrap and autoreformat are
  471.     ignored, so the flags are dimmed.
  472.  
  473.     (13) The final edit-mode toggle concerns hyper mode and ascii mode.  In
  474.     hyper mode, symbolized by a "∞" character, Orpheus hides all linking codes
  475.     and displays your text link anchors in whatever colors you have assigned
  476.  
  477.  
  478.  
  479.                                        8
  480.  
  481.  
  482.  
  483.  
  484.     to them.  In ascii mode, symbolized by a "≡" character, Orpheus displays
  485.     the real contents of your cards, letting you edit the codes manually if
  486.     you wish.  You can toggle from one to other by clicking on the symbol, or
  487.     through the Edit Menu.
  488.  
  489.     (14,16) Square brackets on either side of the line number indicate that
  490.     you have set a temporary left or right margin.  Pressing <Ctrl-[> sets a
  491.     temporary left margin at the cursor position; the same keystroke cancels
  492.     the tempory margin.
  493.  
  494.     (15) Indicates the line on which the cursor is positioned, from 1 to 9999.
  495.  
  496.     (17) The final item on the Statusbar is the name of the current file.  If
  497.     the file has been changed since you last saved it to disk (as shown by an
  498.     asterisk beside the window number), you save it to disk by clicking on the
  499.     filename, or through the File Menu.
  500.  
  501.  
  502.  Using Menus
  503.  
  504.         Orpheus (OH.EXE) is a feature-rich program that new users may find a
  505.     little complex.  Fortunately, the menu system makes it easy to find your
  506.     way around and quickly become an expert.  The best way to learn Orpheus is
  507.     to browse the menus while taking advantage of online Help.  For an
  508.     explanation of any menu item, place the selection bar on it and press
  509.     <F1>, or click on it with the right mouse button.
  510.  
  511.         Pressing <Esc> opens the menu system and preselects the name of the
  512.     last menu opened.  To select a menu, click on its name or press the key
  513.     corresponding to its first letter, or press <Enter> after using the arrow
  514.     keys if necessary to move the selection bar.  To accomplish all that with
  515.     a single keystroke, press <Alt> with the first letter of the desired menu,
  516.     e.g. <Alt-L> for the Link Menu.
  517.  
  518.         Once the menu system is open, you can change menus with the left/right
  519.     arrow keys; for example, if the File Menu is open, press the right arrow
  520.     to open the Edit Menu.  To select an item on a menu, move the selection
  521.     bar to it (using the up/down arrow keys) and press <Enter>.  Alternately,
  522.     just press that item's hilited letter, or click on it with the left mouse
  523.     button.  A very few menu items, such as the first three on the Edit Menu,
  524.     allow you to change a setting without closing the menu.  For example, if
  525.     you click on "Edit mode" on the Edit Menu, or press <Enter> or <Space>
  526.     with that command selected, the setting changes but the menu remains open.
  527.     To close the menu, press <Esc> or click anywhere outside the menu.
  528.  
  529.         While the menu system makes Orpheus easy to learn, keyboard
  530.     accelerators let you bypass the menu as you quickly become an expert.
  531.     Accelerators for menu commands are shown right on the menus, while others
  532.     (for cursor control and so on) are listed in online Help under "Keyboard
  533.     Shortcuts".  If you redefine the keyboard (see the Setup dialog on the
  534.     Other Menu), you'll notice that the menus reflect any related changes you
  535.     make, though Help does not.
  536.  
  537.  
  538.  
  539.                                        9
  540.  
  541.  
  542.  
  543.  
  544.  Using Help
  545.  
  546.         As mentioned above, Help is available on any menu item.  It is also
  547.     available in any dialog -- indeed, any situation whatever -- by pressing
  548.     <F1>.  A particularly useful facility of Help is that you can return to
  549.     the previous help-topic (after leaving Help) by pressing <Alt-F1>.  This
  550.     makes it easier to learn new procedures:  you can read the instructions
  551.     for what you wish to do, exit Help and do as much as you can, then press
  552.     <Alt-F1> to return to exactly the instructions you were reading before.
  553.  
  554.         Virtually all Help topics include hypertext links connected to other
  555.     topics.  The presence of such a link is indicated by a colored word or
  556.     phrase, called a link anchor.  To jump through the link, click on the
  557.     anchor, or move the selection bar to it and press <Enter>.  Use the <Up>
  558.     and <Down> arrow keys to move the selection bar, or to scroll as the case
  559.     may be.  Pressing <Right> is the same as <Enter>, to jump through the
  560.     selected link anchor if any.  Pressing <Left> is the same as <Backspace>,
  561.     to retrace your steps after a series of jumps.  You can also move the
  562.     selection bar by pressing the first letter of any visible link anchor.
  563.  
  564.         You may be interested to know that every feature of the Help
  565.     interface, including the screen design, the command buttons along the
  566.     bottom of the screen, and even the keyboard interface described above,
  567.     was decided by me using exactly the same authoring procedures that you
  568.     will use in working with OH.EXE.  Orpheus Help was in fact written as
  569.     a project using OH.EXE, and the Help interface is encoded in that project,
  570.     NOT in any program code.  The program that performs Help, OHHELP.EXE, is
  571.     a limited subset of the Orpheus Reader.  Though normally it is called
  572.     from within OH.EXE, you can also run OHHELP.EXE as a standalone program.
  573.  
  574.  
  575.  Using Dialogs
  576.  
  577.         Most of what you will do in Orpheus, apart from editing text, is
  578.     accomplished through dialogs.  If you are familiar with virtually any
  579.     contemporary software, you already know how to use the dialogs in Orpheus.
  580.     The results of your dialog selections may be applied to immediate acts
  581.     like making a hypertext link, or may be optionally stored in (for example)
  582.     a configuration file.  All dialogs can be cancelled, and all dialogs
  583.     have complete context-sensitive Help.
  584.  
  585.         In many dialogs, related items are grouped together in boxes.  Before
  586.     the commands or actions in a box can be accessed, the box must be hilited.
  587.     To hilite a box, click on it with the left mouse button, or move the
  588.     selection bar with the <Tab>, <Shift-Tab>, or <Arrow> keys.  If you are
  589.     already in a box and wish to move out of it (to another box or to a
  590.     non-boxed command), either click on the desired location or use the
  591.     <Tab> or <Shift-Tab> keys.  (Within a box, <Up> and <Down> move the
  592.     box's selection bar, while <Left> and <Right> do nothing.)
  593.  
  594.         To select or activate a command in a dialog, click on it with the
  595.     mouse or move the selection bar to it and press <Enter>.  Some commands
  596.  
  597.  
  598.  
  599.                                       10
  600.  
  601.  
  602.  
  603.  
  604.     have hilited action-keys that you can press, while others use non-hilited
  605.     named keys, like <F1:Help>.  The hilited keys in a box can only be used
  606.     when you're in that box; similarly, when you're in a box the only hilited
  607.     keys you can use are those in the box.  However, named keys like <F1:Help>
  608.     can be used at any time, whether you're in a box or not.
  609.  
  610.         While most dialogs are pretty standard -- select an option and move
  611.     on -- a small number have a specialized interface appropriate to their
  612.     special purpose.  An example is the dialog for changing colors (see the
  613.     Other Menu->Setup Orpheus->Change Colors).  Just remember that you are
  614.     never more than a click or a keypress away from online Help.  Every
  615.     dialog's Help topic begins with an illustration of that dialog, with each
  616.     element and procedure thoroughly explained.
  617.  
  618.  
  619.  Customizing Orpheus
  620.  
  621.         Many parts of the Orpheus environment can be customized to suit your
  622.     preferences, needs and work habits.  (You can also customize the
  623.     appearance and behavior of the Orpheus Reader when it loads your finished
  624.     project, but that is another topic.)  As an overview, this section is
  625.     designed to encourage you to try to get the most out of the authoring
  626.     environment -- the most utility and the most enjoyment.  Consult online
  627.     Help for more information when do begin customizing.
  628.  
  629.         All customization begins through the Setup Orpheus dialog, which is
  630.     accessed through the Other menu.  Before examining the various items in
  631.     this dialog, notice that there are two ways to *exit* the dialog:  by
  632.     pressing <F10:Save CFG>, and by pressing <Esc:Cancel>.  With the first
  633.     method, your new settings are saved to a configuration file named OH.CFG.
  634.     The next time you start up OH.EXE, Orpheus will read this file to
  635.     determine how you want things to work.  With the second method however,
  636.     your new settings are not saved to disk -- but they do remain active for
  637.     the current session.  This lets you experiment with various options
  638.     without committing to them (and of course you can always reconfigure even
  639.     after saving OH.CFG).
  640.  
  641.             The sub-dialogs accessed through Setup Orpheus, such as the Color
  642.             dialog, all have <Esc:Cancel> buttons that really do cancel
  643.             changes, restoring whatever settings were in effect before you
  644.             entered that dialog.
  645.  
  646.  
  647.     CHANGING COLORS
  648.  
  649.         The Color dialog lets you set up color schemes, not only for your work
  650.     environment in Orpheus, but for the finished product as displayed by the
  651.     Orpheus Reader.  If you wish, you can store up to 9 different color
  652.     schemes, called palettes, whether to suit the changing demands of your
  653.     eyes or to create a different mood for every project. Each time you
  654.     assemble a finished copy of your work (the version used with the Reader),
  655.     Orpheus builds into it a copy of your *current* color scheme.  Normally the
  656.  
  657.  
  658.  
  659.                                       11
  660.  
  661.  
  662.  
  663.  
  664.     end-user will therefore see your work in the same colors as those in which
  665.     you created it.  This is a very good reason to make sure that you give the
  666.     user access to the Reader's Color dialog; the colors that you find
  667.     relaxing or stimulating may be unbearable (or uninteresting) to your
  668.     intended readers.
  669.  
  670.             All Orpheus programs provide color data appropriate to the user's
  671.             video display hardware, which may be monochrome, grey-scale, or
  672.             color.  Suppose you as an author have a color display:  users
  673.             reading your finished work in color will see the color scheme
  674.             that you designed, but users with mono or grey-scale displays will
  675.             see the appropriate *default* schemes.  (However, if you have
  676.             access to all three types of video display you can design and
  677.             store color schemes for all of them; see Help for details.)
  678.  
  679.  
  680.     PRINT OPTIONS
  681.  
  682.         Printing support in Orpheus is intentionally pretty basic.  You can
  683.     make a standard printout, or export a card or Help topic to an external
  684.     disk file (print to disk).  If you need more refined printing, the
  685.     solution is indirect but simple:  use the print to disk feature, then
  686.     import the resulting text file into your favourite word processor and go
  687.     on from there.
  688.  
  689.         When you use the Print command from the File menu, the Print dialog
  690.     lets you make temporary changes to your print options before you actually
  691.     print.  To make changes that can be saved to OH.CFG, use Print Options
  692.     from the Setup Orpheus dialog.
  693.  
  694.  
  695.     VIRTUAL MEMORY
  696.  
  697.         Virtual memory is the technique of extending conventional memory
  698.     resources by means of swapping:  copying the contents of an area of
  699.     memory to another location, such as XMS memory or a disk file, in order
  700.     to reuse that area for some other purpose.  Orpheus uses virtual memory
  701.     during normal editing and project building, or rather it does so when
  702.     necessary.  If you develop large projects with long text cards, Orpheus
  703.     will use virtual memory a great deal.  In this case you should configure
  704.     Orpheus to give you the best performance possible on your system.
  705.  
  706.         If you have XMS memory available, Orpheus will show this in the
  707.     lower right quadrant of the Virtual Memory dialog.  For best performance,
  708.     tell Orpheus to use XMS.  If you do not have XMS but do have EMS memory,
  709.     you may be able to achieve performance similar to that with XMS.  The
  710.     trick is to use some or all of that EMS as a RAMdrive; consult MS-DOS
  711.     Help on RAMDRIVE.SYS (or your DOS manual) if you don't know how to do
  712.     this.  With a RAMdrive set up, return to the Virtual Memory dialog and
  713.     set the swapfile path to the drive letter assigned to the RAMdrive.
  714.  
  715.  
  716.  
  717.  
  718.  
  719.                                       12
  720.  
  721.  
  722.  
  723.  
  724.         The Virtual Memory dialog can also be used to check out how much
  725.     conventional DOS memory is free for Orpheus to operate with.  Ideally,
  726.     before starting up OH.EXE you should have at least 512K free RAM; you
  727.     can find this out by running the MS-DOS "mem" command.  Returning to
  728.     the Virtual Memory dialog, check the "low RAM free" report.  If it is
  729.     lower than 48K you may need to free up additional DOS memory if you
  730.     develop large projects.
  731.  
  732.  
  733.     DEFINE KEYBOARD
  734.  
  735.         The Define Keyboard dialog lets you customize OH.EXE's response to
  736.     the keyboard.  This is especially handy for common editing tasks, since
  737.     you can adapt Orpheus to behave the same as your favourite word processor.
  738.     Orpheus comes with a small number of built-in keyboard assignments, most
  739.     of which are accelerator keys for tasks listed on the menus.  You can
  740.     redefine the response to any keypress except <F1> and <Esc>.
  741.  
  742.         A complete list of the default keyboard assignments is given in Help
  743.     under "Keyboard Shortcuts".  This list does not reflect any changes you
  744.     might make, so for an accurate account you must browse the list in the
  745.     Define Keyboard dialog.  You'll notice that changes you make *are*
  746.     reflected on the menus, where keyboard accelerators are hilited; however,
  747.     Define Keyboard gives you access to over 60 functions that are not on any
  748.     menu and in some cases do not even have a default keypress.
  749.  
  750.         Note that this dialog only affects the keyboard response of OH.EXE, in
  751.     other words your working environment as an author.  For project-specific
  752.     control over how the Orpheus Reader responds to the keyboard, see Help
  753.     under "Customizing a Project".
  754.  
  755.  
  756.     EXTERNAL EDITOR
  757.  
  758.         Despite the customizations described above and in the next few
  759.     paragraphs, you may prefer to use a more powerful (or more familiar)
  760.     program for serious text editing.  Provided you choose a DOS text editor
  761.     that handles files in plain text format, you can do this quite easily,
  762.     returning to Orpheus only for tasks related to hypertext.  Programs
  763.     recommended for this purpose include Multi-Edit for DOS from American
  764.     Cybernetics, TSE from SemWare, and PC-Write.
  765.  
  766.         To prepare for use of an external editor, start by going through
  767.     Setup to the External Editor dialog, where you can set options to be saved
  768.     in OH.CFG.  To actually run the program you will go through the Edit menu
  769.     and select "External Editor" from there; as with printing, you can then
  770.     make temporary changes to your options that will not be saved to OH.CFG.
  771.  
  772.         Note that the External Editor commands can be applied to *any*
  773.     compatible DOS program, such as a spell-checker.  After running an
  774.     external program Orpheus checks each Edit window to see whether the file
  775.     it contains has changed, and if so, loads in the newer copy from disk.
  776.  
  777.  
  778.  
  779.                                       13
  780.  
  781.  
  782.  
  783.  
  784.     CURSORS
  785.  
  786.         Use the "Cursors" box to set the appearance (size) of the cursor
  787.     in Pushright and Overwrite modes.  For example, if you are using a laptop
  788.     and do not have a utility to make the cursor more visible in all programs,
  789.     you can use this dialog to make the cursor a block.  Most users like to
  790.     use the standard line cursor in Pushright mode and a block cursor in
  791.     Overwrite mode.
  792.  
  793.  
  794.     TABS
  795.  
  796.         Use the "Tabs" box to set the number of spaces in a tab, and
  797.     optionally to make <Tab> insert spaces instead of just moving the cursor.
  798.  
  799.  
  800.     MISCELLANEOUS
  801.  
  802.         There are three options you can set in the Miscellaneous box.  The
  803.     first, ";Text-card comments", refers to how you want Orpheus to interpret
  804.     lines beginning with a ";" character.  If you select this option, Orpheus
  805.     ignores such lines during compilation; you can use this feature to make
  806.     notes to yourself that will not go into your finished work.  The second
  807.     option, "Swap for DOS shell", tells Orpheus whether or not to swap itself
  808.     out if and when you shell to DOS from the File menu.  The swapping code
  809.     for this function will use XMS, EMS, or a disk file, in that order of
  810.     preference, depending on availability.  If neither of the first two is
  811.     available and you have lots of conventional memory left over, you may want
  812.     to leave this option off.  The final Miscellaneous option, "Quit restores
  813.     blink", tells Orpheus whether to restore blink or maintain high-intensity
  814.     backgrounds when you exit the program.
  815.  
  816.  
  817.  
  818.  
  819.  
  820.  
  821.  
  822.  
  823.  
  824.  
  825.  
  826.  
  827.  
  828.  
  829.  
  830.  
  831.  
  832.  
  833.  
  834.  
  835.  
  836.  
  837.  
  838.  
  839.                                      14
  840.  
  841.  
  842.  
  843.  
  844.   ---------------------------------------------------------------------------
  845.                   CHAPTER 3  -  TUTORIAL : A HYPERTEXT PROJECT
  846.   ---------------------------------------------------------------------------
  847.  
  848.  
  849.  
  850.  Topics in this chapter:  What is a Project?
  851.                           How Do You Develop a Project?
  852.                           Starting a New Project
  853.                           Expanding a Project
  854.                           Importing Text
  855.                           Navigating Hypertext in OH.EXE
  856.                           What's in a Card?
  857.                           Finishing a Project
  858.  
  859.  
  860.  
  861.  What is a Project?
  862.  
  863.         In one sense you already know what a project is:  it's that electronic
  864.     guide, manual, book or infobase that you hope to create and distribute
  865.     using Orpheus.  But in terms of actual files on disk, what form does a
  866.     project take during development, and what will it look like when finished?
  867.  
  868.         Here is a schematic of a typical project, showing directories in
  869.     in lowercase letters, filenames in uppercase.  The illustration assumes
  870.     that you have installed Orpheus on drive c: in the \oh2 directory, and
  871.     that the project is named "TEST", but they can be whatever you like.
  872.     Note that only the first item, the working directory, is created by
  873.     you; everything else is generated automatically by Orpheus when needed.
  874.  
  875.         c:\oh2\                ...the "working directory" (you make this)
  876.         c:\oh2\TEST.PRJ        ...the "project file" for TEST
  877.               \test\           ...the "project directory" for TEST
  878.                    \dir1\      ...its first "storage directory"
  879.                    \........   ...more storage directories as needed
  880.                    \dir9999\   ...up to 9999 storage directories
  881.  
  882.         The place where you begin work on a project (your current directory
  883.     when you start up OH.EXE) is called the working directory.  This is the
  884.     only directory you set up yourself.  You can use the same working
  885.     directory as the starting point for any number of projects; it can be
  886.     wherever you installed Orpheus 2.
  887.  
  888.         Except for the project file, everything in your work in progress is
  889.     stored in the project directory and its numbered subdirectories.  The
  890.     parts you will edit yourself -- text you compose or import, and scripts
  891.     to display graphics or perform various actions -- go into special text
  892.     files called "cards", which are named and stored as shown below.  These
  893.     really are text files; you can open them with any text editor or file
  894.     viewer.  They are special because of their filenames, and because each
  895.     begins with a one-line "header" with information used by Orpheus.
  896.  
  897.  
  898.  
  899.                                       15
  900.  
  901.  
  902.  
  903.  
  904.         c:\oh2\test\dir1\1-001.TES   ...a "card" file
  905.                         \.........   ...more cards generated as needed
  906.                         \1-256.TES   ...up to 256 cards per storage directory
  907.  
  908.         Card filenames begin with a two-part number separated by a hyphen,
  909.     and end with a three-letter file extension.  The first part of the number
  910.     corresponds to the directory containing it:  in dir1, filenames start with
  911.     "1-"; in dir2, filenames start with "2-".  The second part is a 3-digit
  912.     number from 001 to 256, corresponding to the fact that a single storage
  913.     directory can hold up to 256 cards.  (In dialogs and linking codes you can
  914.     leave out the extra 0's; for example, 1-1 is the same as 1-001 for all
  915.     purposes except filenames.)  Finally, the three-letter file extension can
  916.     be whatever you wish, provided it is the same for all of the cards in the
  917.     same project; by default, it is drawn from the name of your project.
  918.  
  919.         Since there can be up to 9999 storage directories per project, with
  920.     up to 256 cards per directory, you can have up to 2,559,744 cards -- each
  921.     of unlimited length -- in a single project.  (For comparison, the OH
  922.     project here at Hyperion Softword, provided for your use as online Help,
  923.     handles over half a megabyte of text in a mere 120 or so cards.)
  924.  
  925.         Naturally, the FINISHED version of your project is much more compact,
  926.     consisting of one or more files generated through the final assembly
  927.     stage of the Build process (discussed later in this chapter).  Compiled,
  928.     compressed, and encrypted, these files cannot be edited or changed by
  929.     other users.  However, building a finished product has no effect on the
  930.     unfinished version of your work; therefore, you can expand and edit a
  931.     project indefinitely while generating new versions of the finished product
  932.     whenever you wish.
  933.  
  934.         As shown below, your finished work is deposited in the working
  935.     directory as one or more files named after the project itself.  Often
  936.     there is just one file, normally with "HTX" as the file extension:
  937.  
  938.         c:\oh2\TEST.HTX      ...distribute this with the Orpheus Reader
  939.  
  940.     With large projects there may be additional numbered files:
  941.  
  942.         c:\oh2\TEST.HTX      ...distribute this with the Orpheus Reader, plus:
  943.               \TEST.001
  944.               \TEST.002      ...up to 999 numbered files if needed
  945.  
  946.     If you use the Orpheus Professional option called "Executable HTX", the
  947.     file that would normally end with an HTX extension is merged with the
  948.     Orpheus Reader to become a self-opening book:
  949.  
  950.         c:\oh2\TEST.EXE      ...distribute this only (no separate Reader)
  951.               \TEST.001      ...plus any additional numbered files if created
  952.  
  953.     These illustrations do not show any external files referred to in your
  954.     work, such as graphics or other programs launched from a script.  You
  955.     would have to keep track of them separately.
  956.  
  957.  
  958.  
  959.                                      16
  960.  
  961.  
  962.  
  963.  
  964.  How Do You Develop a Project?
  965.  
  966.         From start to finish, developing a project consists of three phases:
  967.     starting it, expanding it, and generating a finished version of it to
  968.     distribute to end-users.
  969.  
  970.         (1) The first phase, starting, is very brief.  Using the "New Project"
  971.     command on OH.EXE's Project menu, you tell Orpheus the basics of what to
  972.     name your project and where to store it.  Orpheus then produces certain
  973.     startup components (files and directories), comprising the seed from which
  974.     to grow your work in whatever direction you wish.  A step-by-step guide
  975.     through this phase is given in the next section, "Starting a New Project".
  976.  
  977.         (2) The second phase, expanding (along with revision and so on),
  978.     continues indefinitely for as long as you have an unfinished copy of
  979.     your work.  Expanding a project is basically a matter of adding new card
  980.     files and putting something in them.  Normally, this is done through one
  981.     of several commands on the Link menu that simultaneously generate a new
  982.     card and add linking codes that point to it from your current location.
  983.     A step-by-step guide to the most common procedure is given in a later
  984.     section of this chapter, "Expanding a Project".
  985.  
  986.         (3) The third phase, finishing, is as brief as the first -- but can
  987.     be repeated whenever and as often as you wish.  Imagine that you have
  988.     published a beautiful book, complete with full-color graphics and leather
  989.     binding.  The morning after your launch party you find some typos, or
  990.     get inspired to write a new chapter, or come across some groovier
  991.     graphics.  With a printed book you'd be stuck; but with hypertext you
  992.     can just do what you want, tell Orpheus to build a fresh version of the
  993.     finished product, then have another launch party.  All aspects of building
  994.     a finished version are handled through the "Build Project" command on
  995.     OH.EXE's Project menu.  A step-by-step guide to the basic procedure is
  996.     given in the final section of this chapter, "Finishing a Project".
  997.  
  998.  
  999.  Starting a New Project
  1000.  
  1001.         In this section we'll go step by step through the process of starting
  1002.     a new hypertext project in Orpheus.  Our examples will assume that your
  1003.     working directory is "c:\oh2" and that the test project will be named
  1004.     "TEST".
  1005.  
  1006.         Start up OH.EXE at the DOS prompt using the command "oh"; if using
  1007.     Windows or OS/2 do the same as you would to start up any other DOS
  1008.     program (such as File->Run in the Windows Program Manager).  When Orpheus
  1009.     finishes loading you will see its statusbar on the top line, with the
  1010.     cursor under the top left corner, and "?Unnamed?" in the upper right.  Now
  1011.     press <Esc> to open the menu system, followed by <P> to pull down the
  1012.     Project Menu.  (Pressing <Alt-P> would do the same in one step.)  The
  1013.     selection bar is already on "New Project", so press <Enter> to select it.
  1014.     This initiates a sequence of dialogs to guide you through the process;
  1015.     at the conclusion of each dialog Orpheus moves automatically to the next.
  1016.  
  1017.  
  1018.  
  1019.                                      17
  1020.  
  1021.  
  1022.  
  1023.  
  1024.         In Step 1, Orpheus opens a dialog with the title "Enter a New Project
  1025.     (.PRJ) Name".  If you enter a name without an extension, Orpheus appends
  1026.     ".PRJ" to form the name of the project file; but if you do include an
  1027.     extension, it must be ".PRJ".  The root part of the name is then used for
  1028.     the project directory and the other files discussed above.  To continue
  1029.     this tutorial, type in "test" and press <Enter>.
  1030.  
  1031.         In Step 2, Orpheus opens the Project Options dialog.  Notice that the
  1032.     dialog title includes the name of your project:  settings you make in this
  1033.     dialog apply to the current project only.  As you will see, there are lots
  1034.     of things you can do here, in particular customizations of how the Reader
  1035.     will look and respond when it opens your hypertext.
  1036.  
  1037.         Read about these options in online Help.  With one exception, you can
  1038.         change any option at any time during the life of a project; just open
  1039.         the Project menu, select "Project Options", and do it.  The exception
  1040.         is the "Card extension" item in the group box entitled "Your project".
  1041.         This refers to the file extension that will be used for all of the
  1042.         uncompiled cards and certain other files in your work in progress; you
  1043.         can ONLY change this now, during Step 2 of starting a new project.
  1044.  
  1045.     For this tutorial we'll only make one setting, the "Title" for your
  1046.     project.  Type in something appropriate like "Testing, Testing, Testing!"
  1047.     and press <Enter>.  Then press <F10:Done> to conclude the dialog.
  1048.  
  1049.         In Step 3, Orpheus opens the Define Card dialog.  Whenever a new
  1050.     card is created, this dialog comes up so that you can immediately
  1051.     determine certain properties of that card.  (You can change these
  1052.     properties later by selecting "Define Card" from the Card menu.)  Since
  1053.     the most common use for this dialog is to edit a card's Topic entry, you
  1054.     start right off at the Topic item.  A Topic describes the subject or
  1055.     purpose of a card; if you make a habit of ALWAYS entering the Topic when
  1056.     making a new card, you will find that you have a rich resource with which
  1057.     to provide additional forms of access to your work, plus a superb
  1058.     outline for your own use.  In this case, Orpheus is generating the
  1059.     Homecard for your project, so it would be appropriate to type in something
  1060.     like "Table of Contents".
  1061.  
  1062.         With the last dialog concluded, you are in the Homecard of your new
  1063.     project.  That is, you are in an apparently empty text file that happens
  1064.     to be the project's Homecard.  The filename, "1-001.TES" if you are
  1065.     following the tutorial exactly, is shown on the statusbar at the far
  1066.     right.  The line number at the cursor, 1, is left of the filename.  The
  1067.     current window number, 1, is beside the "Esc:Menu" prompt.  And here's what
  1068.     is on your hard disk (details depend on your installation):
  1069.  
  1070.         c:\oh2\TEST.PRJ              ...project file for TEST project
  1071.         c:\oh2\test\                 ...its project directory
  1072.         c:\oh2\test\dir1\            ...its first storage directory
  1073.         c:\oh2\test\dir1\1-001.TES   ...and its default Homecard
  1074.  
  1075.     This constitutes the bare essentials of a project in Orpheus.
  1076.  
  1077.  
  1078.  
  1079.                                      18
  1080.  
  1081.  
  1082.  
  1083.  
  1084.  Expanding a Project
  1085.  
  1086.         In this section and the one following we'll add flesh to your empty
  1087.     Homecard, setting it up like a table of contents.  On each of three titles
  1088.     we'll make a link to a new blank card, then will demonstrate three
  1089.     different methods of putting something in those cards.  Begin by typing
  1090.     the four lines of text below into your Homecard:
  1091.  
  1092.                             TABLE OF CONTENTS
  1093.  
  1094.         How to Read This Book
  1095.         What's New
  1096.         About Orpheus
  1097.  
  1098.         Next, move the cursor to any word in "How to Read This Book".  (Since
  1099.     the number keypad is normally used for hypertext navigation in OH.EXE, you
  1100.     should use the middle keypad for cursor movement.  Alternately, move the
  1101.     mouse pointer to the desired location and click the left button to set the
  1102.     cursor there.)
  1103.  
  1104.         Open the Link menu by pressing <Esc> and then <L>, or simply <Alt-L>.
  1105.     We'll make the standard link type, which is called a "Door" in Orpheus.
  1106.     Since the selection bar is already on the Door command, press <Enter> to
  1107.     select it.  This leads to the following set of dialogs:
  1108.  
  1109.         (1) First comes the Resize Text Anchor dialog.  Notice that the word
  1110.     where you left the cursor before opening the Link menu is now hilited.
  1111.     This represents the default link anchor.  In this case it would make
  1112.     more sense to hilite all of "How to Read This Book" instead of just one
  1113.     word, so the purpose of this dialog is to help you do that right away.
  1114.     The box on the left lets you extend the hilite to either side; the box
  1115.     on the right lets you retract it from either side.  To do this with the
  1116.     keyboard, press <Tab> to select the appropriate box, then press the <Left>
  1117.     or <Right> arrows to extend or retract the hilite.  Using the mouse, just
  1118.     click on the box and then click on the appropriate arrow.  When the link
  1119.     anchor includes the full section title, press or click on <F10:Done>.
  1120.  
  1121.         (2) Next comes a dialog to let you confirm or change the default
  1122.     number assigned to the card by Orpheus.  Most users will never have any
  1123.     need to change this.  Press <F10> to move on to the next step.
  1124.  
  1125.         (3) This brings you to the Define Card dialog, which you saw earlier
  1126.     when the New Project procedure brought you to the Homecard.  The text of
  1127.     the link anchor is offered as the default topic of the new card.  Press
  1128.     <Enter> when the topic is to your satisfaction.  Normally you won't change
  1129.     any of the other options right away, except perhaps the one for "Scroll
  1130.     text" if you left scrolling optional in the Project Options dialog.
  1131.     Notice that in the "Built-in links" box, the "Origin" field contains "1-1";
  1132.     this means that your new card will have an Origin link to card 1-001,
  1133.     where you are right now.  Press <F10> to conclude this dialog.
  1134.  
  1135.  
  1136.  
  1137.  
  1138.  
  1139.                                      19
  1140.  
  1141.  
  1142.  
  1143.  
  1144.         (4) The last dialog lets you select an Edit window in which to load
  1145.     the new blank card.  (Up to this point, if you cancelled one of the three
  1146.     preceding dialogs by pressing <Esc> the entire process would be aborted.
  1147.     However, once you've gotten this far the new card has been created and
  1148.     the linking codes inserted.  Cancelling this dialog merely leaves you
  1149.     in the current window without loading the new card.)  In OH.EXE you can
  1150.     open up to 9 Edit windows.  The dialog lists the first window, containing
  1151.     the Homecard, but hilites window #2 as the logical choice for loading a
  1152.     new card.  Press <Enter> to accept this.
  1153.  
  1154.         Finally you are in your new blank card.  Notice that the filename at
  1155.     the upper right says "1-002.TES", and that the number at the left (beside
  1156.     the Esc:Menu prompt) indicates window #2.  A little later we'll see that
  1157.     there is absolutely no connection between windows and cards, since any
  1158.     window can hold any card or other text file, and you can use any window
  1159.     to navigate throughout an entire project.  For the moment, flesh out
  1160.     the new card by typing in the following two lines of text:
  1161.  
  1162.             If I've forgotten to provide special instructions for how to
  1163.             read this book, just press <F1> and the Reader will explain.
  1164.  
  1165.     This illustrates the most obvious approach to developing a hypertext
  1166.     project:  typing in new text as the project grows.  To save this card to
  1167.     disk, open the File menu and select "Save", or click on the filename on
  1168.     the statusbar.
  1169.  
  1170.  
  1171.  Importing Text
  1172.  
  1173.         In this section we'll continue expanding the Test project, showing two
  1174.     methods of doing so that involve importing text from external files.
  1175.     First we'll import an entire file in one step; then we'll load a long file
  1176.     in a separate window and import just a block of it.
  1177.  
  1178.         To begin, return to the window containing the Homecard.  (You can do
  1179.     this by clicking on the window number, by pressing <Ctl-V> or <Alt-V>, or
  1180.     by using the Window List dialog from the Window menu.)  Move the cursor
  1181.     to the first letter of "What's New".  We're going to make a link on this
  1182.     title, but this time we'll mark the link anchor before opening the Link
  1183.     menu.  This will let us skip the Resize Text Anchor dialog.
  1184.  
  1185.         With the cursor under the "W" of "What's New", press <F3> to begin
  1186.     marking.  Using the middle keypad, move the cursor to the right until the
  1187.     entire title is hilited, or click on the space just to the right of "New".
  1188.     (If you are using an older computer and the right arrow key just makes
  1189.     Orpheus say "bonk", press the NumLock key to switch out of navigation
  1190.     mode.)  With the entire title hilited, press <F3> again to end marking.
  1191.  
  1192.         Now open the Link menu again, press <Enter> to select the Door link
  1193.     type, and follow the dialogs as you did before.  Notice that this time
  1194.     you don't go through the Resize Text Anchor dialog, since you've already
  1195.     marked your link anchor as desired.  When you reach the Window dialog,
  1196.  
  1197.  
  1198.  
  1199.                                      20
  1200.  
  1201.  
  1202.  
  1203.  
  1204.     press <Enter> to load the new card into the window suggested by Orpheus,
  1205.     which should be #3.
  1206.  
  1207.         We'll flesh out this card by importing an entire external text file,
  1208.     in this case the "UPDATE.TXT" file that came with your copy of Orpheus
  1209.     2.  Open the File menu and select "Import File".  If your working
  1210.     directory is the one in which you installed Orpheus, just type in
  1211.     "UPDATE.TXT" and press <Enter>.  If the Orpheus directory is somewhere
  1212.     else, type in the complete path to the file or else <Tab> into the
  1213.     file and directory and boxes until the desired filename is shown in
  1214.     the entry field.
  1215.  
  1216.         With the procedure completed, the entire Update file has been
  1217.     copied into the card in your Orpheus project.  Save this card by clicking
  1218.     on its filename on the statusbar.
  1219.  
  1220.         Return once more to the window containing the Homecard, and make
  1221.     a third link on "About Orpheus".  Follow the dialogs as before, and again
  1222.     load the new blank card into a new window, which should be #4.  We'll
  1223.     flesh out this card by importing only a block of text copied from a much
  1224.     larger file, which will be loaded in another window.  The file we'll use
  1225.     for this purpose is the manual you are now reading.
  1226.  
  1227.         Open the File menu and select "Open".  If your working directory is
  1228.     the one in which you installed Orpheus, just type in "MANUAL.TXT" and
  1229.     press <Enter>.  If the Orpheus directory is somewhere else, type in the
  1230.     complete path to the file or use the file and directory boxes (pressing
  1231.     <Tab> to move into or out of a box) to select the desired file.  When you
  1232.     conclude this dialog, the file is loaded into the next available Edit
  1233.     window, which in this case should be #5.  (If all 9 windows were occupied
  1234.     Orpheus would show you the window list to let you choose which one to
  1235.     use.)
  1236.  
  1237.         You should now be looking at the first page of MANUAL.TXT.  Page down
  1238.     past the copyright line to the first paragraph describing Orpheus.  We'll
  1239.     mark the three paragraphs so they can be copied in a block to your new
  1240.     card.  To make this easy we'll mark the block using line mode.  With the
  1241.     cursor anywhere on the first line of the first paragraph, press <F7> to
  1242.     begin marking in line mode.  Use the <Down> arrow key to move the cursor
  1243.     down to the last line of the third paragraph.  Then press <F7> again to
  1244.     finish marking the block.  (You can also access block-operation commands
  1245.     through the Block menu.)
  1246.  
  1247.         For the next step, return to the window containing your new blank
  1248.     card, using <Alt-V> or by clicking on the window number until you're
  1249.     there.  To insert the marked block from the other window, press <Shift-F3>
  1250.     (or open the Block menu and select "Copy from window").  A dialog will
  1251.     open with a list of all windows containing marked blocks; since there is
  1252.     only one and it is already selected, press <Enter> to confirm it.  The
  1253.     marked block is now copied into your new card.  Press <F5> to unmark this
  1254.     copy, then save this card.
  1255.  
  1256.  
  1257.  
  1258.  
  1259.                                      21
  1260.  
  1261.  
  1262.  
  1263.  
  1264.         At this point your Test project contains three cards linked to the
  1265.     Homecard.  All four cards are in separate full-screen windows, and
  1266.     MANUAL.TXT is in yet another window.  If you were to exit the program now,
  1267.     the next time you loaded the TEST project you would find yourself in
  1268.     the current window, with all the other windows having exactly the same
  1269.     contents as when you left them.  (You can reload a project either from
  1270.     the DOS prompt, giving the project name on the command line, or by
  1271.     selecting "Open Project" from the Project menu.)  Now, what about those
  1272.     links you made?  Do they really give you hypertext, or do you have to
  1273.     switch windows all the time to jump from card to card?  In the next
  1274.     section we'll see that the links really do work -- and that the Edit 
  1275.     windows are only there for your convenience while authoring.
  1276.  
  1277.  
  1278.  Navigating Hypertext in OH.EXE
  1279.  
  1280.         To test hypertext navigation in OH.EXE, we'll start by closing all
  1281.     windows except the one containing the Homecard.  Return to the window
  1282.     containing MANUAL.TXT and press <Alt-F2> to close that window.  This
  1283.     should put you back into window #4, so press <Alt-F2> to close that
  1284.     one, and continue until you are back in window #1 with the Homecard.
  1285.     If you accidentally closed the window containing the Homecard, don't
  1286.     worry about it:  open the Card menu and select "Home" to jump to the
  1287.     Homecard, and complete the jump in the current window (#1).
  1288.  
  1289.         You should now be looking at the Homecard with its three colored
  1290.     links to other cards.  We're going to jump back and forth between each
  1291.     of those cards and the Homecard, first of all in window #1, then with
  1292.     the option of loading the target card in a new window.  If you are using
  1293.     a mouse, it's easy:  using the *left* mouse button, click on a link
  1294.     anchor to set the cursor on it, then click on the cursor to make the jump.
  1295.     Do this now on any of your three links, then retrace your steps (in this
  1296.     case to the Homecard) by clicking the *right* mouse button.  Note that
  1297.     in Help and the Reader it's even simpler, since there's no cursor:  you
  1298.     just left-click once on a link to jump through it, and right-click to
  1299.     return.  For more about navigating with the mouse, read "Navigating
  1300.     Hypertext" in online Help.
  1301.  
  1302.         If you are using the keyboard, navigation is a little more complicated
  1303.     but more powerful in return.  First, notice that all of the navigation
  1304.     commands are available on the Card menu, where the default accelerator
  1305.     keys are given as requiring the Shift key.  What the menu does not show
  1306.     is that those accelerators are limited to the NUMBER KEYPAD, and if you
  1307.     are using a full-sized keyboard on a 286 or higher you do NOT have to use
  1308.     Shift.  However, if you are using an XT (with or without a full-sized
  1309.     keyboard), OR if you are using certain laptop or notebook computers, you
  1310.     may have to turn on NumLock or add Shift as shown on the menu.  In the
  1311.     rest of this section I'll assume that you are using a full-sized keyboard
  1312.     on a 286 or higher.  Later on, you may wish to customize the keyboard for
  1313.     whatever combination of cursor control and navigational commands you find
  1314.     most convenient.  This is done through the "Setup Orpheus" dialog on the
  1315.     Other menu.
  1316.  
  1317.  
  1318.  
  1319.                                      22
  1320.  
  1321.  
  1322.  
  1323.  
  1324.         Continuing now with the keyboard:  using the middle keypad, OR the
  1325.     <Up> or <Down> arrows of the number keypad, move the cursor to the first
  1326.     link, "How to Read This Book".  Now using the number keypad, press
  1327.     <Right>.  This should jump you through the link and to the attached card,
  1328.     without leaving window #1.  To retrace your steps, press the <Left> arrow
  1329.     on the number keypad.  (You could also press <Home>, but the point is that
  1330.     <Left> retraces your hypertext jumps no matter where you are, whereas
  1331.     <Home> goes straight to the Homecard.)  Repeat this procedure with the
  1332.     second and third links, just to verify the hypertext connection.
  1333.  
  1334.         Now we'll do the same thing but with the option to load the target
  1335.     card in another window.  The purpose of this ability is to make your
  1336.     work easier while authoring; there is no equivalent in the Reader.  To
  1337.     use the window facility, hold down the Control key while giving your
  1338.     normal navigational command.  This applies whether you are using the
  1339.     keyboard or the mouse.  After jumping to each card, give the same retrace
  1340.     command as you did before (right-click or the <Left> numpad arrow)
  1341.     *without* using the Control key.  Notice that Orpheus returns to window #1
  1342.     because the Homecard (your destination) is already loaded there.  Repeat
  1343.     the procedure until all three child cards are loaded in separate windows.
  1344.  
  1345.         To find out more about navigating hypertext in Orpheus, be sure to
  1346.     check online Help on the topic "Navigating Hypertext".
  1347.  
  1348.  
  1349.  What's in a Card?
  1350.  
  1351.         Now that you have made some links (and some cards), and used them,
  1352.     it's time you saw what is actually in those cards that enables Orpheus
  1353.     to give you hypertext linking.  Return to the Homecard if you are not
  1354.     there already.  Now press <Ctl-F1>.  This switches Orpheus into "ascii
  1355.     mode", in which it displays the card's true contents.  As you can see, in
  1356.     ascii mode your link anchors are shown with the embedded codes revealed.
  1357.     This is exactly what you would see if you were to load the Homecard file
  1358.     in any standard text editor or file viewer.  If you press <Ctl-F1> again
  1359.     Orpheus will return to "hyper mode", in which it displays your links the
  1360.     way your end-users will see them.
  1361.  
  1362.         Still in ascii mode, press the <Up> arrow to move the cursor to the
  1363.     top of the Homecard, then once more to scroll up to a line that was
  1364.     formerly invisible.  This line is the card header, and will look
  1365.     something like this:
  1366.  
  1367.             OH2(TEXT,"Table of Contents")
  1368.  
  1369.     Every uncompiled card in an Orpheus project begins with a header line
  1370.     of a similar nature.  The header tells Orpheus what type of card it is,
  1371.     what its topic is (if any), and so on.  For further discussion of cards
  1372.     and the various contents of header lines, read "Hypertext Cards" in Help.
  1373.     (You don't need to know anything about headers to use Orpheus, as long as
  1374.     you are aware that they exist.)
  1375.  
  1376.  
  1377.  
  1378.  
  1379.                                      23
  1380.  
  1381.  
  1382.  
  1383.  
  1384.         If you press <Ctl-F1> a few times to toggle back and forth between
  1385.     ascii mode and hyper mode, you may notice that besides the changing
  1386.     display of your text, there is one small change on the statusbar.  In
  1387.     hyper mode, the symbol to the left of the line number is a figure 8 on
  1388.     its side (the infinity symbol).  In ascii mode the symbol is a stack of
  1389.     three horizontal lines.  The current mode is also indicated when you
  1390.     open the Edit menu.
  1391.  
  1392.         Let's take a closer look at your three link anchors in ascii mode.
  1393.     Unlike the card header, which you should never need to edit manually,
  1394.     link anchors and the other embedded codes are good things to know about.
  1395.     Depending on the work you do, you may never need to leave hyper mode,
  1396.     and if that's the case, you'll never edit a linking code manually.  But
  1397.     it's comforting to know that should you ever need to create or edit the
  1398.     linking codes yourself, you CAN do so, and do it easily; and for a few
  1399.     advanced functions you do in fact have to.
  1400.  
  1401.         As you can see by the patterns repeated in the three sets of
  1402.     linking codes on your Homecard, every link anchor begins with a "<"
  1403.     left angle bracket, which is followed by the visible text of the link
  1404.     anchor.  Then comes a "|" pipe symbol, followed by more codes and a
  1405.     final ">" right angle bracket.  The "<|>" characters are the skeleton
  1406.     of every embedded code in Orpheus, with visible text going on the left
  1407.     of the "|", and the actual codes on the right.  In the case of your three
  1408.     links, the codes all begin with a "D" (if you have followed the tutorial
  1409.     exactly), which represents a Door link.  This is followed by a two part
  1410.     number -- "1-2", "1-3", and "1-4" -- which you will recognize as referring
  1411.     to the linked cards 1-002.TES, 1-003.TES, and 1-004.TES respectively.  (In
  1412.     filenames the second part of the number must be padded with 0's to make
  1413.     three digits, as in "1-002"; but in link references and dialogs you can
  1414.     omit the 0's.)
  1415.  
  1416.         Although there's a lot more to linking than we can cover in a brief
  1417.     tutorial, there is certainly no mystery about it, nor is Orpheus
  1418.     particularly complicated.  Read up on "Hypertext Links" in Help, check
  1419.     out the individual commands on the Link menu, experiment.
  1420.  
  1421.  
  1422.  Finishing a Project
  1423.  
  1424.         In this section we'll build a finished copy of the Test project,
  1425.     and see how it runs in the Orpheus Reader.  Then we'll examine the
  1426.     virtues of incremental compilation, and try out the Simulator.
  1427.  
  1428.         With the Test project loaded in OH.EXE, open the Project menu and
  1429.     select "Build".  (For a full explanation of everything you see, press <F1>
  1430.     while in this dialog.)  The most important part of the Build Project
  1431.     dialog is the "Action" box in the lower right corner.  As you can see, it
  1432.     lets you choose among 7 combinations of three actions:  compile, verify,
  1433.     and assemble.  We need all three steps to build a finished product, so
  1434.     press <4> to select "Compile->Verify->Assemble".  Then press <F10:Begin>
  1435.     to set the builder in motion.
  1436.  
  1437.  
  1438.  
  1439.                                      24
  1440.  
  1441.  
  1442.  
  1443.  
  1444.         If all goes well, Orpheus will swiftly compile your cards, verify all
  1445.     links accessible from the Homecard, and assemble the results into a
  1446.     finished product named after your project:  in this case, TEST.HTX.  When
  1447.     building is completed, press a key to clear the report window.
  1448.  
  1449.         Now let's try out the Reader!  Exit OH.EXE, either through the File
  1450.     menu or by pressing <Alt-F4>.  Start up the Reader (OHREAD.EXE) with
  1451.     the following command at the DOS prompt (we assume that the project name
  1452.     is "test"):
  1453.  
  1454.                     ohread test
  1455.  
  1456.     The Reader should open your project to the Homecard.  Unless you have
  1457.     already played around with customizing your project options, the Reader
  1458.     will display your work using the default Reader interface and the default
  1459.     screen layout, which includes a simple titlebar.  All of this can be
  1460.     extensively customized.
  1461.  
  1462.         Press <Esc> to open the Reader's menu system, and explore a little.
  1463.     You can customize, on a project-specific basis, end-user access to
  1464.     features like printing, or even to the menu system as a whole.  Press
  1465.     <F1> while in any dialog or while looking a text card (but not while in
  1466.     a menu).  Notice that the Reader provides a series of simple Help windows
  1467.     for all built-in features -- but this too can be customized.
  1468.  
  1469.         Try out your links, observing how the Reader responds to keyboard and
  1470.     mouse input.  Apart from the fact that everything is simpler (there's no
  1471.     distinction between the number keypad and the middle keypad, for example),
  1472.     you also have a choice between two sets of keyboard assignments.  Actually
  1473.     you're seeing only a fraction of what you *could* see, because the fact
  1474.     is that through OH.EXE's Project Options dialog you can customize your
  1475.     work so thoroughly that the Reader will look as if it was programmed
  1476.     just for you.
  1477.  
  1478.         When you're ready, exit the Reader through the File menu or by
  1479.     pressing <Alt-X>.  If you have a robust file-viewer like LIST.COM, you
  1480.     might enjoy sneaking a peak at the contents of your finished product,
  1481.     TEST.HTX.  What you'll see is:  completely indecipherable garbage.  In
  1482.     other words, only the Reader can read it, and no one can hack a finished
  1483.     version of your work.
  1484.  
  1485.         Now let's get back into OH.EXE to check out something else.  Load
  1486.     up the Test project again, either by giving its name on the command
  1487.     line ("oh test"), or by using the "Open Project" command on the Project
  1488.     menu.  We're going to see how you can test your finished work without
  1489.     leaving OH.EXE, and without actually building a fully finished copy.
  1490.     We'll do this using the Simulator (OHSIM.EXE), which you can run both
  1491.     as a program in its own right, or (more conveniently) from within OH.EXE.
  1492.  
  1493.         Open the Project menu and select "Simulate Reader".  This tells
  1494.     Orpheus to fire up the Simulator; if all goes well, a message will appear
  1495.     reminding you of the Simulator's "emergency exit", which is <Alt-F4>.
  1496.  
  1497.  
  1498.  
  1499.                                      25
  1500.  
  1501.  
  1502.  
  1503.  
  1504.     (The emergency exit is there in case you intentionally disable the
  1505.     standard exit hotkey -- as a project option -- and forget to replace it
  1506.     with some other way for users to exit your work.)  Once past that message
  1507.     you should see exactly what you saw in the Reader.  However, if you try
  1508.     to open the menus you'll discover that the Simulator doesn't have any,
  1509.     because it isn't a full copy of the Reader.  The Simulator has to do
  1510.     certain things that the Reader does not, so in order to keep the program
  1511.     a reasonable size any unnecessary parts have been left out.
  1512.  
  1513.         Unlike the Reader, which uses a *fully assembled* copy of your work,
  1514.     the Simulator only uses the compiled (but not assembled) portions of it,
  1515.     which reside in your project's "CMP" files.  CMP files are generated
  1516.     during the compile stage of the build process; there is one in each
  1517.     storage directory, to hold compiled versions of all of the cards in that
  1518.     directory.  The assembly stage puts together your finished work by
  1519.     copying these compiled parts found in the CMP files.
  1520.  
  1521.         Let's demonstrate further the difference between Reader and Simulator.
  1522.     If you are still in the Simulator, press <Alt-F4> to exit it.  With your
  1523.     project loaded in OH.EXE, type a line or so of text in whatever card you
  1524.     happen to be in, and save that card.  Now open the Project menu and
  1525.     select "Compile, Simulate".  This tells Orpheus to look for any cards that
  1526.     have changed or been added since the last compilation, compile them,
  1527.     and then open the Simulator.  When the process is complete you will again
  1528.     be in the Simulator, looking at the compiled card with the new text that
  1529.     you just typed in.  However, if you were to exit the Simulator and OH.EXE
  1530.     and then load up your project in the Reader as we did earlier, you would
  1531.     find that the Reader displays the old version of the card, because the
  1532.     HTX has not changed.  To update the HTX, open the Build dialog and choose
  1533.     any action that includes the assembly stage.
  1534.  
  1535.         Though the Edit windows of OH.EXE give you a pretty good view of what
  1536.     your work will look like in the Reader, the Simulator takes you one step
  1537.     closer to the goal without the extra processing required to build the
  1538.     final product.  Besides this purpose, the Simulator is also used for
  1539.     testing scripts and adding hotspots to graphics.
  1540.  
  1541.         Summing up:  for a real project, you would devote a certain amount
  1542.     of time to tuning your project options and customizing the appearance and
  1543.     functionality of the Reader interface.  This and many related topics are
  1544.     covered extensively in online Help:  on the Help Contents page, select
  1545.     "Finishing a Project" and explore.  Over time you will dig into Help on
  1546.     various topics encountered in the Project Options, Build Project, and
  1547.     other dialogs, but some of the topics reached through "Finishing a
  1548.     Project" touch on wider considerations, such as distributing your work to
  1549.     end-users.
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.                                      26
  1560.  
  1561.