Hall of Fame/HallofFameCDROM.cdr/util4/grab-bag.lzh/VARITALE.ARC/VARITALE.DOC

Text File | 1989-01-01 | 17KB | 567 lines

                       THE VARITALE AUTHORING SYSTEM

                              Release: C1.00








                             Operator's Manual

                            Spring 1987 Edition







                     P I N N A C L E   S O F T W A R E

                     P.O. Box 163 Cartierville Station
                     Montreal, Quebec, Canada  H4K 2J5

                              [phone]







                                  NOTICES

This  publication  could  include  technical  inaccuracies  or typographical
errors.

Changes are periodically made to the information herein;  these changes will
be incorporated in new editions of this publication.

Requests for  copies of this product and for technical information about the
system should be made to your authorized VariTale  dealer or  to the address
indicated in the licensing agreement.

The VariTale product is Copyright (C) 1987 by Pinnacle Software.


Upgrades and Support

If  you  are  a  registered  user  of  the full-feature (15-book) commercial
version of this product, you  will  be  granted  a  special  account  on "Le
Systeme Online",  a Montreal-based multiple-node information network.  (Call
[phone] at 300/1200/2400 baud, using 8N1).  You may  use this account
to  send  your  comments  via  electronic  mail  to the user named "Pinnacle
Software".  You may also  download  any  upgrades  or  new  versions  of the
product, using a standard protocol such as XMODEM.

This support  arrangement will  remain in  effect for  one year,  and may be
renewed each year for $20.  If VariTale is popular amongst your users -- and
we believe it will be -- you can easily get them to support it.


Private Information

The information  contained in  this manual is intended only for operators of
VariTale installations.  You  are requested  to keep  it private.   Under no
circumstances may this manual be copied in any way.


Dedication

(From Timothy Campbell, creator of VariTale)

The inspiration  for VariTale  came from  many sources,  but one significant
influence was the HyperText system proposed by computer  guru Ted  Nelson in
his book  "Computer Lib/Dream Machines".  If you haven't read it, you owe it
to yourself to get your hands on a copy.  Whence the sequel, Ted?

Note, though, that VariTale is not  HyperText  and  makes  no  claim  to be.
Everything is deeply intertwingled, but some things more so than others.



            ii






   NOTICES . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  ii
   Upgrades and Support
   Private Information
   Dedication

   WHAT IS VARITALE? . . . . . . . . . . . . . . . . . . . . . . . . . .   1

   INSTALLING VARITALE . . . . . . . . . . . . . . . . . . . . . . . . .   2
   What You Need
   Installation Steps
   Getting Things Rolling

   DOOR OPERATION  . . . . . . . . . . . . . . . . . . . . . . . . . . .   3

   MULTI-USER OPERATION  . . . . . . . . . . . . . . . . . . . . . . . .   4
   File Locking
   The Unique File-locking Tag
   Single-Processor Operation
   LAN Operation

   MAINTENANCE . . . . . . . . . . . . . . . . . . . . . . . . . . . . .   6
   Backups
   Librarian Commands
   BURN
   CLOSE
   RENAME
   Why Show the Commands?

























                                                                                       iii





                             WHAT IS VARITALE?

VariTale is  a "branching  authoring system", designed to run either locally
or as a "Door" on BBS systems such as PCBoard, RBBS, NoChange, Fido, ROS and
so on.

You will  be able  to write stories (known in VariTale as "books") that have
alternate chapters.  Here is an example of a branching tale:


        .---------------- I woke up -----------------.
        :                                            :
.------ I went back to sleep ----.              .--- I made breakfast ---.
:                                :              :                        :
I dreamed up a new program   I had no dreams    It was bad     It was good


At any point, there is always an alternative.  In VariTale, each step (known
in VariTale  as "chapters")  can be  up to  50 lines long.  After each step,
there can be up to 5 alternatives.

This allows you and other people to create  "story-rounds", in  which every-
body contributes  chapters to  the tale.   Story-rounds are quite popular on
BBS systems, but there is a problem:   somebody will  take the  story in the
wrong direction,  and the other writers get annoyed.  And that is the end of
that story.

With  VariTale,  the  writers  can  propose  alternate  chapters,  either in
response to  an inappropriate effort by another writer, or simply to explore
a different facet of the story.























                                                                                         1





                            INSTALLING VARITALE


What You Need

VariTale is very easy to install.  It will runs  MS- or  PC-DOS Version 2.00
and higher, on any 128K IBM-PC or compatible.

VariTale should  be run  on a  hard disk  if you  expect any kind of serious
traffic on the program.   Its  file-handling  is  quite  efficient,  but the
chapters can  stack up  quite quickly.  Apart from that, though, there is no
reason why it cannot be run on floppies.


Installation Steps

To get VariTale running on your system, follow these steps:

   1.   Make a backup copy of the original diskette.

   2.   Prepare a destination for the VariTale files.

        A.   If using a hard disk, this means creating  a directory, usually
             named VARITALE.

        B.   If using floppies, this means formatting a diskette.

   3.   Copy the  necessary files from the original diskette to their proper
        place (on a hard disk or a floppy).  Use the DOS COPY command  to do
        this.

   4.   Configure VariTale  to work  according to your wants and needs.  The
        CONFIG program will take you through the necessary steps.

   5.   Run a local test.  The VARITALE command will do this.  This runs the
        program locally, with absolutely no reference to the modem.  You can
        run VariTale in this manner at any time.

   6.   If you wish to run VariTale as a Door, refer to the "Door Operation"
        section of this manual.


Getting Things Rolling

On some  BBS's, VariTale  needs a little push to establish it as a regularly
used feature of the system.   People are  not encouraged  to start  a story-
round if  they feel  they're alone.   You  should get  a few budding writers
together, have them pick a rough plot, then start at the same time.





            2





                              DOOR OPERATION


This manual is not intended to be a  tutorial for  door operations.   Please
consult your host BBS's documentation for full details.

In general, you will create a batch (.BAT) file which will call up VariTale,
using a special start-up command that will be  explained shortly.   VariTale
handles problems  such as  lost carriers,  so there  is no need for watchdog
timers and suchlike things.

To start up VariTale, place the following command in your door batch file:

                 VARITALE /DOOR/user-name/time-left/port

user-name ....... If omitted, none assumed
                  This is optional.  It is used only in the  activity report
                  generated by the CLOSE command if you are running a multi-
                  user system.

time-left ....... If omitted, assumes 60 minutes maximum visit time

port ............ Current port address, in decimal
                  If omitted, assumes default port from CONFIG.DAT
                  If 0, no modem reference (i.e. console)
                  If D, door is forced opened (use after  system crash ONLY)

Here are some examples...

VARITALE /DOOR                 No name assumed, 60 minutes, default port
VARITALE /DOOR//15/0           No name assumed, 15 minutes, console
VARITALE /DOOR/JOE SMITH/60    For Joe Smith, 1 hour on default port
VARITALE /DOOR///1016          No name, 60 minutes, on COM1 (decimal 1016)
VARITALE /DOOR///A1016         With system ID for LAN use (explained later)

Information such  as real-name,  time-left and  port can  be determined by a
program you write to build a command line.  On  a multi-port  system, such a
program  is  not  optional;  you  must  pass information to be used for file
locking purposes.   If  are running  a LAN,  you may  have to  pass a system
identifier letter.  See "Multi-User Operation" for details.

We will  be collecting appropriate command-line builder programs for various
BBS systems.  See the "Upgrades and Support" section for more information.










                                                                                         3





                           MULTI-USER OPERATION


This section is directed towards users of multi-port systems.   You can skip
it if you configured VariTale for a single-user system.


File Locking

"Locking"  means  claiming  exclusive  use  of  a  resource.  In the case of
VariTale, for instance, it means that a book can be used only  by one person
at a time.

VariTale  does  its  own  file  locking.    It does not use the file locking
provided with DOS 3 and higher, nor does it use  locking techniques  such as
the one  provided by MultiLink.  VariTale's locking technique is slower than
that provided by the aforementioned products.   On  the other  hand, it does
allow you to run VariTale under a wide range of environments.

It's slower  because all  locking information  is recorded in the .LOK file,
using a "collision detection" scheme.  This is  obviously has  lower perfor-
mance  than  a  RAM-based  locking  table, but it minimizes interaction with
other products, thereby maximizing compatibility.

If you are running a LAN  (Local Area  Network), be  careful of disk-caching
software because  this might  prevent locking  information from reaching the
locking file  properly.    VariTale  synchronizes  locking  file  updates by
performing a  dummy write  before checking  for collision, but a cache would
make this approach useless if it withholds disk writes.

There is one major problem with a disk-based locking table:  if  your system
crashes,  it  will  faithfully  remember  the  locking data!  This data will
"time-out" after an hour (the maximum  time  allowed  in  VariTale),  so the
problem isn't  deadly.   You can  clear the locking data by using the "clear
door" command:

                           VARITALE /DOOR///D/

Not only does this open  the  door  (if  closed  previously  with  the CLOSE
command), but  it will  also reset  all locking  data.   This version of the
command can be executed only at the console or a local workstation.  You can
skip this  step, but  your users  will have to wait a while for any locks to
time out.

We regret any inconvenience that may be caused by our locking scheme.   It's
a compromise  which ensures  that VariTale  will run on almost any computer,
network, DOS or multi-tasker.






            4





The Unique File-locking Tag

VariTale performs a lock  by writing  a locking  record, performing  a dummy
write to  de-synchronize itself in certain environments, then re-reading the
record to see if  it has  been altered.   If  it has,  it means  somebody is
competing for the same resource.  In such a case, the lock is not acquired.

In order  to determine  if a "collision" has taken place (i.e. more than one
user is competing for the same resource), VariTale  must have  a unique item
of data associated with each user.  This is absolutely essential.

VariTale compares port, user-name and system identification data.


Single-Processor Operation

If you  are running  a single-processor system (using a multi-tasker such as
Multi-Link, Desqview, etc.) each  of your  users will  have a  different COM
port.   In this case, you need only pass the port address to VariTale on the
start-up line (e.g. VARITALE  /DOOR/name/time/port).    This  information is
used both for file locking and setting up communications.


LAN Operation

If you  are using  a LAN,  all of your users may have the same port address.
In this case,  the  "port"  parameter  should  include  an  arbitrary system
identification  to  permit  file  locking.    Prefix the port address with a
letter (anything from ASCII decimal 65 to ASCII decimal 122 -- that is, A to
Z uppercase,  some intervening  special characters, and a to z lowercase) to
provide a system identification to provide a unique locking tag.

Here's an example:

VARITALE /DOOR/JOE SMITH/45/X1016       <-- System "X", on COM1

Alternately, you may rely on the user-name as  the unique  tag if  (and only
if) you  are certain  that there will never be two people with the same name
using VariTale.  (That includes "System Operator", of course.)














                                                                                         5





                                MAINTENANCE


Backups

Under normal circumstances,  VariTale  should  be  totally self-maintaining.
However,  it  is  possible  that  a  system crash could cause the index file
(.TOC) to be corrupted.

To deal with this  possibility, VariTale  comes with  a batch  program named
BACK.    This  copies  the  data  files  to a sub-directory of your VARITALE
directory, named BACK.  To make your first backup, enter these commands:

   CD VARITALE              <-- Change to your VariTale directory
   MD BACK                  <-- Create the safe-keeping directory
   BACK                     <-- Make a backup

Should your files get  messed up  somehow, you  can restore  the last backup
with the RESTORE command.

This  technique  is  by  no  means  as  good as performing regular full-disk
backups, but it is quick.  Please run BACK at  least every  few days.   Your
users will  be heart-broken if their masterpieces suddenly disappear because
you didn't have a recent backup.


Librarian Commands

The librarian commands are enabled with the ENABLE  command.   This will ask
for a  password.   This is  initially set  to "bookworm",  but this can (and
should) be changed with the CONFIG program.

There are three special commands for the librarian:  BURN, CLOSE and RENAME.


BURN

This command removes a  book from  the list.   This  also deletes  the files
associated with  the book.   If you want to preserve them for posterity, you
can copy them to a floppy.  Each book has two files (.TOC and  .VTB).  Thus,
to preserve  book #1, you'd copy VARIA.TOC and also VARIA.VTB.  Book #2 uses
VARIB.TOC and VARIB.VTB, and so on.

VariTale comes with two  dreadful sample  stories named  "The Secret  of the
Broken Sword"  and "Space  Terror!".  Feel free to use them to test the BURN
command.







            6





CLOSE

This command prevents further users from entering VariTale  unless they have
the librarian's  password.  If they type it in correctly, the library is re-
opened.  It can also be re-opened by using the  "D" option  explained in the
"Multi-User Operation" section.

This command  is only  useful on  a multi-user system, of course.  It allows
you to keep people out of the program while you  are performing maintenance,
such as the RESTORE described in the "Maintenance" section.


PRUNE

This command  is used to delete a chapter.  You might do this if the chapter
is offensive either to your morals or literary taste.

PRUNE deletes only a single chapter and the pointer from a previous chapter.
It does  not delete  all the  branches emanating  from the chapter.  You may
have to PRUNE many times if you're doing a major clean-up.

PRUNE does not  compress  the  book  file,  either;  it  simply  removes the
pointers associated  with the  chapter and  blanks out its title so it won't
show up.  You will gain no additional disk space by PRUNEing.


RENAME

This command lets you rename a book.  You may wish to  do this  if the story
branches away from the premise implied by the original title.  It can not be
used to rename a chapter.


Why Show the Commands?

You may be curious why the  HELP command  shows the  librarian's commands in
addition to  the usual  commands.  No doubt, some system operators will feel
that this is private information and that it's  none of  the users' business
what he can do.

On the  other hand, if the users know what commands you have available, they
might not bother you with requests that you can't deal with, such  as "Can I
move a  chapter after another one?"  No, you can't, and any observant person
will probably figure this out -- which will save time for both of you.









                                                                                         7