                      Copyright 1996, Hyperion Softword

                    *************************************
                    *  Orpheus 2, beta release 2.00.30  *
                    *************************************

                Comments and queries to:  Hyperion Softword,
                535 Duvernay, Sherbrooke, QC J1L 1Y8, Canada
                    tel/fax - 819-566-6296 (Rod Willmot)
                       email - willmot@interlinx.qc.ca


    ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::
    ((((((((((((((((((((   Orpheus 2  User's Guide   )))))))))))))))))))))
    ::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

Last revised: March 28, 1996


    TABLE OF CONTENTS
==============================================================================

    Notice
    Shareware
    Acknowledgments

    Part I - Setup
        1. Introduction
        2. Installing Orpheus 2
        3. Notes for Beta Testers

    Part II - A Look Around
        4. What's New
        5. What's Missing

    Part III - Tutorial
        6. Starting a new project
        7. Making a Link
        8. Navigating Links
        9. Importing Text
       10. Loading an existing Project
       11. Building a finished Product

    Appendix - How to Order

==============================================================================



                                 = Notice =
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

  * THIS IS THE FINAL BETA RELEASE.  

  * THIS FILE IS NOT A MANUAL.  99% of the documentation for Orpheus 2 is
    in online Help.  (Press <F1> in OH.EXE for context-sensitive help from
    any menu, dialog, or other situation; you can also run OHHELP.EXE from
    the DOS prompt.)

  * If you have projects developed with Orpheus 1.nn, you can use the
    included utility OH1TO2.EXE to convert them to the new file formats
    used by Orpheus 2.  See OH1TO2.TXT for more information.  Do not mix
    up Orpheus 2 files with your old files!




                                = Shareware =
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

  * Orpheus is currently distributed as shareware.  As an unregistered user
    you are welcome to evaluate this copy for up to 30 days.  You may not
    distribute anything you might create with Orpheus 2, in any way, without
    purchasing a registered copy.  Documents created with an unregistered copy
    invoke a warning message when performed by the Reader.

  * The price of Orpheus is $79 US, plus shipping.  Yes, you can register
    with your credit card!  For full details please see "How to Order" at
    the end of this file, or use the order form provided in REGISTER.TXT.
    A small number of advanced features require purchase of Orpheus
    Professional at $149 US; these are fully discussed in online Help.

  * If you purchased an earlier version of Orpheus you are entitled to an
    upgrade.  Users who registered at the full current price of $79 US will
    receive a free upgrade directly from me, as soon as Orpheus 2 is deemed
    complete.  If you are unsure of your status and wish to know what an
    upgrade will cost (if anything), give me a call.




                             = Acknowledgments =
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

  * Warm thanks to the beta testers who have contributed to the story
    so far:  Ray Ballard, Andy Roberts, Wim Berden and the guys at ILS,
    Joost van der Gaag.

  * Thanks in many tongues to all those who have worked on translations
    of the Orpheus Reader:  Daniel Marois, Marc Coulombe, Jan Moens,
    Jurgen Nijhuis, Paul de Kamp, Thorsten Glattki, Giovanni Calesini,
    Jesus de Paula Assis, Ernesto Eduardo Casin, Alexander E. Gubin.

  * Special thanks to the tireless sysop of Synapse BBS, Daniel Coulombe.

  * Orpheus uses the SPAWNO routines by Ralf Brown to minimize memory
    use while shelling to DOS and running other programs.



                             = Part I - Setup =
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

-----------------------
    1. Introduction
=======================
    What is Orpheus?
    System requirements
    What can it do?
    Windows version
    Shareware...

    What is Orpheus?  Orpheus is a hypertext authoring system.  It is
designed for the creation of compiled hypertext documents that can be read
with the Orpheus Reader.  Registered users may distribute such documents
(together with the Reader) any way they please:  on disk, over BBS systems and
the Internet, or installed on a LAN.

    System requirements:  Orpheus runs on any IBM-compatible PC from
the XT on up to the Pentium.  Orpheus is currently a DOS-based system,
requiring DOS 3.1 or higher; it runs very happily under Windows and OS/2.
The authoring program requires a hard disk and at least 512K of RAM; for
best performance XMS is desirable.  The Reader can run on diskette, and
survives on much less RAM.

    What can it do?  Orpheus 2 has a capacity of over 2 million linked
nodes in a single document.  Text cards can be of any length.  Graphics
support now includes SVGA modes, and you can display PCX, GIF, and FLI/FLC
files.  Through script commands you can create a work that interacts
exquisitely with the user.  You can modify the appearance and behavior of the
Orpheus Reader so that it looks like it was custom-programmed for you.

    Windows version:  The code in Orpheus 2 was designed for easy portability
to Windows-based programming.  As soon as Orpheus 2 is complete, I will begin
work on a Windows version of the Reader.

    Shareware...  Yes, Orpheus 2 is shareware, as was Orpheus 1.  If you are
not a registered user of Orpheus 2, you are welcome to evaluate it for up to
30 days; you are NOT permitted to distribute (in any way) works that you may
have created with Orpheus 2.  The price of Orpheus 2 is $79 US, plus shipping.
If I haven't provided ordering information in this release, please contact me
by one of the methods given at the top of this file.  NOTE:  registered users
of Orpheus 1.nn can receive an upgrade; please contact me.



-------------------------------
    2. Installing Orpheus 2
===============================
    Orpheus 1 users
    Orpheus 2 "Interim Version"
    Typical installation

    Orpheus 1 users:  If you have used Orpheus 1 in the past, be sure to
install Orpheus 2 in a completely different directory.  The only "contact"
between the versions should be via the Converter, OH1TO2.EXE, if you intend
to convert your old projects to the new system.

    Orpheus 2 "Interim Version" users:  do as above.  The file formats of
the "real" Orpheus 2 (this one) bear no similarity to the Interim Version.
User the Converter to change your Interim projects to the new system (see
OH1TO2.TXT).

    Typical installation:  Place your Orpheus 2 files into a directory of
their own on your hard drive, such as:

            C:\OH2

From now on you can use that location as your "working directory" for all
of your projects.  For example, in DOS you would switch to that directory
and start up OH.EXE with the command "OH"; your projects would be based in
that directory, with their files all stored in subdirectories created for
you by Orpheus.  See below in this file for discussion of starting a new
project and loading an existing project.



---------------------------------
    3. Notes for Beta Testers
=================================
    Memcheck
    Known bugs

Check out UPDATE.TXT for a list of changes, fixes, and new features.

Memcheck
============
Beta versions of Orpheus now incorporate the Memcheck debugging tool
from StratosWare Corporation.  Besides helping you discover bugs, Memcheck
will protect your work and your system from unexpected behavior.  To activate
Memcheck your DOS environment must include the MEMCHECK variable, which is
done by giving the following command at the DOS prompt, =before= running
OH.EXE:

    SET MEMCHECK=1

This command can be placed in your autoexec.bat file, or in a batch file
used only for running the beta.  The following batch file could be named
OH2.BAT or BETA.BAT, and would optionally pass a project-name parameter to
Orpheus:

    SET MEMCHECK=1
    OH %1
    SET MEMCHECK=

The last command removes the MEMCHECK variable from your DOS environment,
and can also be given manually.  Whenever Memcheck encounters a serious
memory-related error while you are running OH.EXE, a message box will
pop up reporting the problem.  Please note what the message says, along
with some indication of what you had been doing before the error occurred.
When you press a key to clear the message, Orpheus will safely exit.

I find that debugging is especially convenient under Windows, i.e. in a
DOS box.  If the program appears to freeze -- no disk activity, no
response to the keyboard -- you can safely terminate it using the Windows
trick of pressing Alt-Space, selecting "Settings", then "Terminate".

NOTE:  Memcheck code is also present in the Simulator and the Reader, but
not in Help.  Does this have any bearing on whether you can distribute a
beta version of the Reader to your users?  None at all.  Unless they
themselves set the MEMCHECK variable on their systems, the Memcheck code
does not run.


Known bugs
==============
As of March 28, 1996:  none.


                         = Part II - A Look Around =
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

---------------------
    4. What's New
=====================
    Ascii file format
    Scrollable text
    Better linking
    System capacity
    Better compiling
    Improved compression
    Simpler Reader
    Customize Reader interface
    Disable Reader elements
    Selector keys in Reader
    Extended graphics support
    Hotspots improved
    Menu() command
    Ask() command
    Run() & Runbat() improved
    Data Fields
    Color schemes
    The Simulator


    * Ascii file format:  Uncompiled cards are now plain text files.  This
means that you can create them with any text editor, though more commonly
you'll switch into ascii mode (within OH.EXE) for plain-text editing.  In
ascii mode you can see the link codes and edit them manually (it's easy).  The
great advantage of the new file format:  if something goes wrong, you can fix
it.  In Orpheus 1 the files were semi-binary, and trouble meant trouble.

    * Scrollable text:  Text cards can be scrollable if you wish, with no
restriction on length.  Many users of Orpheus 1 liked the screen-sized cards,
and you can still use them if you don't like scrolling, or limit scrolling
to particular cards.

    * Better linking:  First, link numbers now correspond in a perfectly
obvious way to the filenames of the cards they point to.  Second, linking
itself is more flexible, and as mentioned above, easy to do manually in the
rare cases when you need to.  Crosslinks (as a link type) are toast; now you
can link anywhere as often as you want, using the standard link types.  There
are several new link types, including Exit links (actions to perform when a
user leaves a card), Private links (they don't go into the finished product),
Report links (to print instead of the card shown onscreen), and more.  Orpheus
two extends the use of link codes to handle embedded labels and hilites; both
dress up the text with color, and labels can also be used as link targets.

    * System capacity:  The new system is built to handle over 2 million
unique nodes, i.e. individual linked cards, of which Text cards can be of
any length.  Finished products are designed for extremely fast performance
in the Reader, no matter how large the work.

    * Incremental compiling:  The old system combined all phases of finished-
product-making into one process, which you had to repeat from the beginning
if an error was encountered.  Orpheus 2 separates "building" into three
stages:  compiling cards into their individual finished, compressed form,
in which they are stored in CMP files; verifying the links to all possible
cards in the work, starting from the Homecard; assembling all compiled cards
(and other elements) into a finished product.  The first stage, compilation,
can now be performed incrementally; once a given card has been compiled you
no longer have to recompile it, no matter how often you compile new cards
or assemble versions of the finished product.  This is a huge time-saver.

    * Improved compression:  Finished products are now significantly smaller
than under Orpheus 1, particularly if you take advantage of the ability to
use scrollable text (as opposed to stringing together many screen-sized
cards using "More" links).  Along with this there is better security:  whereas
an HTX compiled with Orpheus 1 could be deciphered without difficulty, and
certain parts could be left in plain text, under Orpheus 2 an HTX file looks
like 100% binary garbage.  Any part too small to compress efficiently is
encrypted.

    *Improved distribution:  In terms of finished output, the old system
produced a small HTX file with at least one numbered subfile; subfiles were
limited to 64K.  Orpheus 2 lets you set the maximum filesize up to 1 megabyte,
which includes the HTX file.  This means you can now assemble most projects
into *one* file, the HTX, for simpler distribution.  (With Orpheus 
Professional you can assemble into a self-reading EXE with *no* other files.)

    * Simpler Reader:  The old Reader had a number of automatic features that,
while intended to be friendly, could be troublesome.  For example, the user
could always open the menu system and shell to DOS, which could be dangerous
if the Reader was being used on a BBS.  Currently the Reader for Orpheus 2
is still "missing" the odd feature that made the old one stand out, but it's
clear that =authors= will be happy that the Reader no longer forces it on
them.  In keeping with this, whenever I add an interface-related feature to
the Reader I will make it possible for authors to hide or disable it.  See
online Help:  Contents->Orpheus Utilities->The Reader->Feature Set.

    * Customize Reader interface:  You can customize the Reader interface
(primarily as evidenced in text mode) in a number of ways.  Open the Project
Menu, select Project Options, then dig into the Screen Layout dialog.  Read
online Help about this and about making command buttons.  You can make an
interface all your own; an example is Help itself, which is NOT hard-coded
into the Help engine, rather it was set up as the Help project's layout, and
you can do the same with your own projects.

    * Disable Reader elements:  All of the built-in Reader elements (such as
the menu system) can be disabled through the Project Options dialog.  You can
also disable the hotkeys (like the one to exit the Reader) and force the user
to do things through your own popup menus and/or command buttons.

    * Extended graphics support:  Orpheus 2 now supports SVGA graphics up
to mode 29.  You can display GIF graphics as well as PCX, and I've added
support for animation using FLI/FLC files.

    * Hotspots improved:  Hotspots now are drawn as convex polygons rather
than blocky shapes; the new method gives you the same resolution as the
image onscreen, making for real precision.  In addition, hotspots can be
"linked" to a sequence of script lines immediately following a hotspot
command; you are no longer limited to linking hotspots to other cards.

    * Menu() command:  the new script command menu() lets you display a
popup menu; you can respond to the user's menu selection to call various
internal Reader functions, to perform other script commands, or to initiate
a hypertext jump.

    * Ask() command:  the new script command ask() lets you display a popup
dialog, similar to a standard Orpheus dialog.  You can respond to the user's
selection with the same flexibility as described above for the menu() command.

    * Run() & Runbat() improved:  control whether the Reader swaps itself out
before performing the command (e.g. if you're launching a very large external
program you'd want the Reader to swap out).  You can also control whether the
Reader clears the screen; this lets you use these commands for special effects
while displaying graphics.

    * Color schemes:  Colors are now stored for three video standards -- mono,
grey-scale, and color -- and if you have all three available while working you
can select your own schemes for each and keep them in a single CFG file.
The colors active on your system when you assemble a finished product are
built into the HTX.  If you selected "Your colors" in Project Options, the
user sees your work first in your colors; otherwise the default colors appear.
However, if the user has a Reader CFG file present, he sees with his own
colors, but can still call yours through the Color Dialog -- if you give him
access to it.

    * The Simulator:  As a complement to incremental compilation, Orpheus 2
gives you a way to experience your work as if you were seeing it in the
Reader, but without having to produce a finished copy of it.  The Simulator
works with CMP files (described above) -- the stored compiled forms of your
individual cards.  The Simulator lets you test scripts realistically, and is
the environment you'll use for drawing hotspots.


-------------------------
    5. What's Missing
=========================

A number of useful features that were in Orpheus 1.65 haven't been plugged
in yet; a few are now obsolete and won't be.

Currently the graphic file formats supported are SPR, PCX and GIF, with
FLI/FLC for animation.  I should be able to add the new PNG format as
soon as I can get the code.  Many Orpheus 1 users took advantage of the
ability to store graphics etc in library files; Orpheus 2 will replace
this by optionally including them in the actual finished document.  It
will be a whole lot easier, simplifying script commands and eliminating the
need to figure out a library-management program.  It's all designed, just
not coded yet!  Look for INCLUDE on the Project Menu, in future releases.

Missing from the Reader currently are some of the gadgets that were in
Orpheus 1.65:  a Bookmark dialog, a Tour capability, the ability to shell
to DOS (universally disliked by authors).  The Reader now includes Print
and Color dialogs, a Notepad (superior to the old one), and a simpler menu
system.  A new and extremely powerful feature is full-text search, as
illustrated in online Help; this one requires use of the Indexer and an
Orpheus Professional licence.




                           = Part III - Tutorial =
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

---------------------------------
    6. Starting a new project
=================================

Start up OH.EXE using the command "oh" at the DOS prompt.  (Do not give a
filename on the command line when you are beginning a new project.) Open the
Project Menu and select "New Project".  This leads you into a sequence of
three dialogs:  the first to enter a name for the project, the second to set
your project options, and the third to define the project's Homecard.

(1) The first dialog prompts you for the name of a new Project File, which
must end in ".PRJ".  If you enter a name without an extension, Orpheus appends
.PRJ automatically; if you include an extension, it must be .PRJ. For example,
you can type "TEST" and the new Project File will be named "TEST.PRJ".

(2) The second dialog lets you set various project options; these settings
will apply only to the current project.  The Project Options dialog can also
be accessed separately through the Project Menu, and you can set or change any
option later on (with one exception) whenever you like.  The exception is the
"Card Extension" used for uncompiled cards and certain other files; by default
it is the first three letters of the project name, such as TES for TEST.PRJ.
You can ONLY change it during the sequence for making a new project.  For now,
enter a title for your work and continue.  For online Help about all of your
project options, press <F1> while in this dialog.

(3) The third dialog, Define Card, opens automatically whenever a new card is
created.  The settings you make in this dialog apply ONLY to the current card,
and can be changed whenever you like.  For the most part the only item you
will regularly concern yourself with is the Topic.  Topics are a new feature
of Orpheus 2, which you can read about in online Help.  A Topic describes
the subject of a card; if you make a habit of *always* entering the Topic when
making a new card, you will find that you have a rich resource for providing
additional forms of access to your work, plus a superb outline for your own
use.  For now, type in a Topic (such as "Table of Contents") and continue.
For online Help about all of your card options, press <F1> while in this
dialog.

With the last dialog concluded, you are in the Homecard of your new project.
As shown on the Statusbar (upper right on your screen), the Homecard is named
"1-001.TES".  The window number, 1, is shown at the left of the Statusbar
beside the "Esc:Menu" prompt.  The line number at the cursor, 1, is shown to
the left of the filename.  For an explanation of everything you see on the
Statusbar, press <F1> and select "Statusbar" from the Help Contents page.

At this point you now have the skeleton of a complete project.  Using the
"TEST" example for illustration, you have a project file (TEST.PRJ), a
Homecard (1-001.TES), a project directory with the same name as your
project, and the first storage directory for uncompiled cards.  Supposing
that you installed Orpheus 2 in a directory named C:\OH2, here is what
you would have:

    C:\OH2\TEST.PRJ                - project file for TEST project
    C:\OH2\TEST\                   - project directory for TEST project
    C:\OH2\TEST\DIR1\              - first storage directory in project
    C:\OH2\TEST\DIR1\1-001.TES     - default Homecard for the project

If you have been using earlier versions of Orpheus you'll notice some
differences here -- for the better.  For an explanation of how Orpheus 2
names and stores your files, press <F1> and select "Files & Directories"
from the Help Contents page.



------------------------
    7. Making a Link
========================

The next step is to begin entering text and making links.  If you are new
to Orpheus, at this point you might appreciate a little clarification.  In
some hypertext systems, you start off with a collection of your own existing
files and proceed to create links among them; the links might be stored
separately in a database, or added to your files in the form of special codes.
Orpheus takes a different approach.  All parts of an uncompiled Orpheus
project are special files created for you by Orpheus and stored in special
directories.

    Hypertext files are called "cards" in Orpheus; they are actually plain
    ascii text files (in Orpheus 2).  What's special about them is that,
    (1) each begins with a one-line "header" with certain information about
    it, and (2) each has a unique filename identifying it as a numbered part
    of the project.  For example, the Homecard created in the previous
    section, if you typed in the suggested Topic, would have a header line
    something like "OH(TEXT,"Table of Contents")".  This means that it's a
    Text card whose Topic is "Table of Contents".  As for the number of the
    card, in this case 1-001, its significance is that whenever you make a
    link to that card the target code is just "1-1".  You don't have to type
    in long filepaths that could become invalid, in fact normally you don't
    type in linking codes at all -- Orpheus does it for you.

Whenever you want to add a new part to an Orpheus project, you begin by
making a link to a new blank card; then you jump to that card and either
type in or import whatever you want that part to contain.  Suppose then
that you have a collection of text files that you want to turn into hypertext
using Orpheus.  You'll proceed by importing them, either whole or a section
at a time, into card files created on demand as your project grows.  You
can also compose new material in a card just by typing it -- the heart of
OH.EXE is a word processor -- and you can make as many crosslinks as you want
between cards in the same project.

So let's try this out.  Assuming you're in the Homecard, type in something
like "Table of Contents", hit <Enter> a few times to bring the cursor down,
and type in "Chapter 1: Excited about Oatmeal".  We'll make a link on the
chapter title, automatically generating a new blank card as the target of
the link.

    1. If you are new to Orpheus, put the cursor on the word "Chapter" or
    click on it with the mouse.  If you already know Orpheus, mark the
    entire title.

    2. Now press <Alt-L> to open the Link Menu; we'll make this a "Door"
    link, the standard link type when the target is a Text card.  Press <Enter>
    to select "Door", and follow the dialogs.

    3. If you didn't start off by marking the link anchor, Orpheus will hilite
    the word at the cursor and let you "resize" the anchor -- extend it left
    or right to include the whole title.  If you did start off by marking it,
    Orpheus skips this stage.

    4. The next step is a dialog concerning the number that will be assigned
    to the new blank card.  Since Orpheus has already figured out the next
    available number (in this case 1-002), normally you'll just hit <Enter>
    here; do it.

    5. Now the Define Card dialog comes up.  You saw this earlier when you
    were making your Homecard.  As before, Orpheus really wants you to provide
    a Topic for the card, so type in something like "Why I get mushy over
    oatmeal".  You don't =have= to do anything else in this dialog, but
    later on, if you want to change some of the "built-in" features of that
    card, you can open the Define Card dialog through the Card Menu.

    6. Finally, one last dialog comes up to select a window for the new
    card.  (To learn about Orpheus 2's window capabilities, press <F1>
    while in this dialog, or select "Edit Windows" from the Help Contents
    page.)  Whenever you create a new card, Orpheus gives you the following
    options:  (a) load it in the current window, replacing whatever is there
    at the time; (b) load it in another open window, replacing whatever is
    there at the time; (c) load it in a new window, unless you already have
    9 windows open (the limit); or (d) don't load it at all.  Note that if
    you choose options (a) or (b), the existing contents of those windows
    ARE NOT ERASED, though they are removed from memory.  Instead, they're
    left safely on disk as your cards or other files, and you can get to them
    again whenever you wish.

    For the present demonstration, hit <Enter> to load the new card in a
    new window.

If you've followed step by step through this little tutorial, you are now
looking at a blank card linked to the Homecard.  Type in something
scintillating, like "Some people call oatmeal "porridge", and I just think
that's horrid." Press <F2> to save your wisdom.



---------------------------
    8. Navigating Links
===========================

Now for a brief test of hypertext navigation in Orpheus.  We'll assume that
you have followed the tutorial so far and are looking at card 1-002.TES
loaded in window 2 (the window number is on the Statusbar, just right of
"Esc:Menu").  Using the number keypad, press the <Home> key.  This should
take you back to your Homecard with the Table of Contents.

    If it didn't, you have an XT or perhaps a laptop; press the NumLock key to
    turn on navigation, then press <Home>.

Note that besides being back in the Homecard, you are also back in window 1.
This is because OH.EXE checks whether the card you're jumping to is already
in another window, and if so, switches windows instead of reloading the card
from disk.  Now let's jump through the link anchor you made earlier:  click
on any part of it to set the cursor there (use the left button for this), then
click right on the cursor.  Or using the number keypad, press <Down> to move
the cursor to the link anchor, then press <Right> to jump through it.

Once again we're in card 1-002.TES and in window 2.  Time to find out whether
these WINDOWS have anything to do with your hypertext CARDS (they don't).
Let's close window 2.  Press <Alt-F2> to close the current window, or go the
long way around by opening the Window Menu -- <Alt-W> -- and selecting
"Close".  This puts us back in window 1 and the Homecard, and you can verify
that this is the only window by pressing <Ctl-F2>, which opens the Window List
dialog.  Only window 1 is open.  The purpose of this exercise is to show you
that your cards have an existence independent of what windows they're loaded
in (or not loaded in), and that the links you make are permanent until you
change them.  To prove it, jump through the link anchor as you did in the
previous paragraph.  Notice that after the jump you're still in window 1.
This time we'll return to the Homecard by using the Retrace method (retraces
your steps):  click the right button, or press <Left> on the number keypad.

Now we'll do the jump one more time, but will use a trick to load the target
card in a DIFFERENT window.  Hold down the <Ctl> key, then do whatever you
did before to jump through the link anchor -- click on the cursor after
setting it on the link anchor, or press <Down> to it then <Right>.  This time,
because you were holding down <Ctl>, Orpheus opens the "Select Window for
Jump" dialog.  Press <Enter> to select the offered window, which is #2.
To verify that both cards are now loaded in separate windows, press either
<Alt-V> or <Ctl-V> a few times (until you tire of switching windows).

Each of the 9 edit windows in OH.EXE can hold any text file of any length,
including of course your own cards in a project.  You can load different
windows with the same card, to work with different parts of it.  You can
hide windows to facilitate rapid switching between those you're working in.
For more information, go to the Contents page of Help and click on "Edit
Windows" or on "Window" at the bottom.

Perhaps right now you're finding all this flexibility a wee bit complicated.
Okay, YOU can master it sure enough, but will your eventual readers have to
know all this when they get your finished products.  No way.  The Orpheus
Reader offers a much simpler navigational interface and does it all in a
single window (the screen!).  Moreover, you can customize many aspects of the
Reader's functionality, including which keys on the keyboard perform
navigation.  For more information go to the Contents page of Help and click
on "Customizing a Project".



-------------------------
    9. Importing Text
=========================

In Orpheus 2, you no longer have to load external files into a special
Fileview window in order to import text from existing files.  All windows are
now Edit windows, each can hold any text file of any length, and each file can
have its own marked blocks.

There are two ways to import text in Orpheus 2:  the quick way imports an
entire file at once; the slow way lets you import selected blocks.  For the
quick way, place the cursor on the line where you want the imported text to
begin; now open the File Menu and select "Import File", then type in the name
of the file to import, or <Tab> to the Files box and choose it from the list.
(Use one of the smaller TXT files for purposes of demonstration.)  The entire
file is copied into the current card, beginning at the line where you left the
cursor.  (If there was already text at or below that line, it is moved to the
end of the imported material.)

To import selected blocks of text you will use a slightly different procedure.
Open the File Menu, select "Open", then choose the file to load, such as this
one, README.TXT.  Assuming you're following this tutorial and haven't filled
all 9 windows yet, the file will be loaded into the next available window.

    README.TXT uses the angle brackets "<>" to indicate keypresses such as
    <F1>.  This is an ancient convention decided upon by wizards (at a
    convention) and I see nothing wrong with it.  However, Orpheus 2 uses the
    same symbols to indicate embedded hypertext links.  If you switch windows
    over to the one containing the Homecard, you can see the link embedded
    around your chapter title by pressing <Ctl-F1>.  Press <Ctl-F1> again
    to see the link anchor the way we all prefer.  What you've just done
    is toggle back and forth between "ascii mode" (where you see everything
    just as it is) and "hyper mode" (where embedded codes are hidden and
    link anchors are colored).  If you look at the statusbar to the right
    of center, notice that a  symbol (infinity) appears when you're in
    hyper mode, while a  symbol (sheaf of papers) appears in ascii mode.

    Get back into hyper mode and switch windows over to the README.TXT.
    Scroll or page down a bit, and pretty quickly Orpheus will pop up a
    message box saying "Incomplete or misplaced link codes".  This is
    because Orpheus tries to interpret what it thinks are embedded link
    codes, and informs you of what seems to be an error.  Press <Enter> to
    clear the message; note that Orpheus has switched automatically into
    ascii mode.  NOW if you switch windows back to your Homecard you'll
    notice that you're still in ascii mode even though your hypertext cards
    are error-free.  (I may change this behavior, but not the next part.)
    Get back into hyper mode while in the Homecard, then switch windows back
    to README.TXT.  Notice that Orpheus has figured out what you want: the
    window with README.TXT stays in ascii mode (without an error message)
    and the windows with your cards stay in hyper mode.

Let's see, what were we... Oh yeah, importing text.  To import a selected
block of text rather than a complete file, start by loading the source
file (in this case README.TXT) into another window; you've just done that.
Now mark the text you wish to import.  The easy way (and the safest if
you have a BETA version of Orpheus 2) is to place the cursor on the first
line of the text you want, press <F7> to begin line marking, scroll down
to the end of what you want, and press <F7> again to end marking.  Now
switch windows to one of your cards.  Place the cursor where you want to
insert the imported text, and press <Shift-F3> to copy it there.  Since that
is the Copy-from-window command, Orpheus opens a dialog to let you select
the window with the block you wish to copy; there's only one right now, so
just press <Enter>.  With the copy complete, press <F5> to unmark the
inserted copy, or <F4> if you've changed your mind (this deletes it).  Now
return to README.TXT, where your original marked block is still there.  Press
<F5> to unmark it.

One final point:  if any of the text you import into a hypertext card
contains the <> angle bracket characters (for non-linking purposes), you will
have to "escape them" before Orpheus will consider your cards error-free.
This is a simple matter of inserting a backslash "\", which wizards refer to
as an escape code, in front of each such character.  You'll also have to do
this if you wish to *display* a backslash, i.e. you'll need "\\" in order
to see "\".  HOT TIP: if you type a <, a >, or a \ while in HYPER MODE,
Orpheus automatically inserts the escape code \ in front of it.

For more information on linking codes, go to the Contents page in Help
and click on "Hypertext Links", then "Codes used in embedded links" or
"Using the escape code".

By the way, this may be a good time to mention that you can get Help on
all kinds of things without having to navigate through Help itself.  For
example, if you open the File Menu and click the right mouse button (not
the left) on "Import File", Orpheus pops up Help on exactly that subject.
Or do it with the keyboard:  move the menu selection bar to "Import File"
and press <F1>.


---------------------------------------
    10. Loading an existing project
=======================================

Before exploring any other facets of Orpheus 2, let's see how to reload your
new project in a later session.  First, press <Alt-F4> to quit OH.EXE (or open
the File Menu and select "Exit").  At the beginning of this tutorial, you
started up OH.EXE with just the "oh" command at the DOS prompt (without any
parameters).  Now that you've created a project, you can reload it when you
start OH.EXE by adding its name to the command line.  For example, to reload
the TEST project you would enter "oh test".

After reloading the TEST project, check your windows and observe that
everything is as you left it when you exited.  Whenever you quit a project,
either in exiting the program or in switching to a different project, Orpheus
saves your desktop for the project in a STATUS file, stored in the project
directory.

You can also start up OH.EXE with "oh", then open the Project Menu, select
"Open Project", and type in the name of the project to load.  Use the same
method later to switch from one project to another.  (Since you can only load
one project at a time, Orpheus saves the current project's STATUS file, clears
all windows, then loads the new project after reading it's STATUS file.)



---------------------------------------
    11. Building a finished product
=======================================

The one-step Compile Project command in Orpheus 1 has been replaced by the
Build Project dialog on the Project Menu.  While you can still produce a
finished product with a single command, the Build dialog gives you access
to the intermediate steps, for an enormous increase in speed and convenience.

    Users who have worked with certain other hypertext systems are often
    afraid that "building a finished product" means losing their UNfinished
    work or the ability to change it.  Not so with Orpheus.  None of the
    Build stages has the slightest effect on your uncompiled cards.  You can
    build and distribute a finished version on Monday, make corrections or
    additions on Tuesday, and send out a new version on Wednesday (or as
    often and as quickly as you like).

With your TEST project loaded, open the Project Menu and select "Build".
As you can see, this dialog offers you a number of options, but all of the
action takes place with a single keypress, <F10:Begin>.  Normally, you'll
leave your options at the most convenient settings:  in the Scope box,
select "Project"; this means that when looking for cards to compile, Orpheus
checks the entire project.  In the Selection box, select "Compile if new or
changed"; this tells Orpheus not to waste time recompiling cards that have
already been compiled.  The Options box you can ignore for the time being, but
later you may want to increase the "Largest file" setting; this tells Orpheus
when to stop adding to one finished-product file and start another.  Finally,
the Action box is where you tell Orpheus which of the build stages to perform
when you press <F10>.

    In the Compile stage, Orpheus compiles your cards into the form they'll
    have in your finished product:  Text cards are compressed, while Graphic
    and Event cards are transformed from English-language scripts into binary
    code.  Compiled cards are stored in files with a "CMP" extension, one
    for each storage directory in a project.  The Simulator (a simulation
    of the Orpheus Reader) works exclusively with CMP files.

    The Verify stage starts out from the Homecard and, using link-records
    stored in the CMP files, explores every possible link it can find to every
    card or data field in your project.  If a card contains a link to
    something you've deleted, Verify finds the problem and tells you about it;
    if a link that should point to an Event card points to a Text card (or
    vice-versa), Verify tells you about it.  At the end of verification a
    complete list of *everything* needed to go into your finished product is
    stored in the NODELIST file in your project directory.

    The Assemble stage consults the NODELIST and puts together your finished
    product, drawing upon the precompiled parts stored in your CMP files and
    elsewhere.  It is extremely fast.  If you make a minor change to a project
    that has already been assembled, such as a new color scheme, you can
    reassemble the project (skipping the other two stages) and have a new
    finished product in seconds.

By default, the Action box is set to #1, "Compile only".  This is because
you have no need of the other stages during most of the development period
that you will devote to a given project.  Why assemble a finished product
you're only half way there?  On the other hand, *compiling* should be done
on a regular basis throughout development, at the end of the day or when you
take a coffee break.  No, you don't HAVE to do it, but I advise it, for two
reasons.  First, as long as the Selection box is set to "Compile if new or
changed", you will compile incrementally, catching only those cards that you
have added or edited since last compiling.  This means that regular compiling
doesn't waste you any time, while it does promise extremely fast final-assembly
when the time comes.  Second, anything that is compiled can be viewed in the
Simulator, which looks and behaves just like the Reader when it loads your
finished product.  (If you use Graphic and/or Event cards, you'll depend on
the Simulator to debug your scripts.)

Now let's do a test build of the TEST project.  For this demonstration I'd
like you to change the Action box setting to #4, "Compile->Verify->Assemble".
When this is done, press <F10:Begin> and watch the builder go to work.

Fast enough for you?  Now let's see what your cards look like in the
Simulator.  Open the Project Menu and select "Simulate Reader".  A message
box reminds you that you can hotkey out of the Simulator by pressing <Alt-F4>.
(This is an emergency exit in case you paint yourself into a corner later on:
if you disable the default Exit hotkey -- <Alt-X> in the English-language
version -- and if you forget to provide an Exit command button of your own,
you won't have any other out except a reboot.)  Once in the Simulator, you'll
notice the presence of a titlebar displaying the title of your project and a
couple of command buttons.  (As of version 2.00.17 the Esc:Menu button does
nothing, neither in the Simulator nor if you use it in the Reader.  Check
the documentation on this if you have a later version.)

Important to know right now:  YOU DO NOT HAVE TO USE THIS TITLEBAR IN YOUR OWN
WORK.  Later on, open the Project Menu and select "Project Options", then
"Screen Layout".  Check it out and press <F1> for guidance.  You can customize
the appearance and functionality of your work in many, many ways.  An example
is online Help, which as I may have mentioned, was created as an Orpheus
project.  The appearance of Help, including the command buttons along the
bottom row, was set up in the Screen Layout dialog.  You can use a frame, a
titlebar, a commandbar, and put buttons and topics and your title upon them,
but you can also use absolutely none of these, or pick and choose and work up
a layout that looks custom-programmed.

Exit the Simulator with <Alt-X> or <Alt-F4>.  Now let's test your work in
the Orpheus Reader, since you assembled an HTX as the end result of your
build command.  Quit OH.EXE by pressing <Alt-F4>.  At the DOS prompt, start
up the Reader with the name of the project as the sole parameter:

        ohread test

The Reader should load TEST.HTX, and it will look exactly like what you just
saw in the Simulator.  The difference is that, if you are a registered user,
you can distribute your HTX with the Orpheus Reader, or install it on a LAN
as a corporate (or institutional) information system.  Press <Alt-X> to exit
the Reader.

Now you have seen the bare essentials of how to use Orpheus.  The rest is up
to you.  We've touched on only a fraction of what you can achieve with this
system, but most of it is as easy as what we've just done.  Explore the menus
and dialogs, dig into Help, experiment.  MAKE STUFF, and keep in touch.



Rod Willmot     => willmot@interlinx.qc.ca
==============================================================================



                         = Appendix - How to Order =
:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::

The following order form is also provided separately in REGISTER.TXT.



                                   ORDER FORM

    Please send me a registered copy of the latest version of Orpheus.
    I understand that I will receive a Licence granting me the right to
    sell, give away, or otherwise distribute any compiled electronic works
    that I create with Orpheus, along with the Orpheus Reader.  In accepting
    this Licence I agree not to compile and distribute works created by
    others using shareware copies of Orpheus.


 +=====+=========================================+=======+============+=======+
 | Qty |            Product Description          | Price |  Shipping  | Total |
 +=====+=========================================+=======+============+=======+
 |     |                                         |       | US/Can  $3 |       |
 |  1  | Orpheus Hypertext Authoring System      | $79 US| Other   $6 | _____ |
 +-----+-----------------------------------------+-------+------------+-------+
 |     |  For an affordable site licence, or for a customized version |       |
 |     |  built to your specifications, please call 1-819-566-6296.   |   -   |
 +=====+=========================================+=======+============+=======+
                * Prices are in US dollars*                    Total  | _____ |
                                                                      +=======+

    Name:    ________________________________________________
    Address: ________________________________________________
             ________________________________________________
             ________________________________________________
    Phone:   (work)_________________  (home)_________________
    Fax:     ______________________
    Email:   ________________________________________________

    Preferred disk format:  [_] 3.5-inch (720K)     [_] 5.25-inch (360K)
                            [_] 3.5-inch (1.44M)    [_] 5.25-inch (1.2M)

    Method of payment:  [_] check or money order enclosed
                        [_] purchase order # ____________________
                        [_] credit card (see below)

      *Canadian and overseas orders must be in US dollars, OR the equivalent
       value in Canadian dollars according to the exchange rate when ordering.

    I have Version ____ of Orpheus, obtained from: ___________________________

    Comments: ________________________________________________________________
              ________________________________________________________________


                               Hyperion Softword
                               535 Duvernay
                               Sherbrooke, QC
                               Canada J1L 1Y8

     *** U.S. customers:  Please use a 40-cent stamp on mail to Canada. ***

 ============================================================================
                           * Credit Card Orders *
 ============================================================================

The following information tells how to purchase Orpheus by credit card.
Credit card orders are processed by Public Software Library, a fine company
located in Houston, Texas (USA).  When it receives your order, PSL sends
me a fax with your name and address, and I mail you your registered copy of
the latest version of Orpheus.  From then on you are a customer of Hyperion
Softword, receiving information, tech support, upgrades, directly from me.

If you need information about Orpheus, call Hyperion Softword, not PSL!
PSL cannot tell you anything about Orpheus, but I certainly can.  You can
reach Hyperion Softword at 819-566-6296 (email: willmot@interlinx.qc.ca).


===============================================================================
Credit card order of Orpheus (PSL #11142) from Public Software Library:

Fax:   713-524-6398
Voice:   713-524-6394
CIS:  71355,470
Post:  Public Software Library, P.O. Box 35705, Houston, TX 77235-5705, USA.

      * Please enter your name as it appears on your card,
      * and the address where you receive your credit card bills.

Name:
Address:


Shipping address (if different):


Telephone:
Fax:
Email:

Credit card:  [  ] Visa    [  ] Mastercard    [  ] American Express
              [  ] Discover

Card number: _________________________________ Expiry: ________________

Signature: ____________________________________

===============================================================================
