(More documents and stuff have been installed in /usr/local/ktrove)

			     Kallisti Trove 1.0


                For All Your Removeable Card Needs. Sort Of.
               A Fine Service of The Barry BitTwister Cabal.
                                 Hail Eris.


                                 WARNING!!!
THIS HAS SOME RISKS ASSOCIATED WITH IT!!  THE BBC WISHES EVERYONE TO LIVE IN
       PARADISE, BUT ON OUR BUDGET ALL WE CAN DO IS YELL ABOUT IT.
                   READ THE "WARNING" SECTION BELOW


Now that we've got that over with, be sure to read the rest of this as well. Or
better.

Contents
--------

    WARNING
    REQUIREMENTS
    THEORY OF OPERATION
    HOW TO USE THIS BLASTED THING
        COMMAND LINE OPERATION
        GUI OPERATION
    EXPERT ISSUES
        Customizing the File List
        Manual Repairs
    SUPPORT


KTrove (for short) grew from the Z's oppressive limitations regarding where
programs get installed and used.  Oh, sure, you can TRY and pick something
other than RAM.  Something innocuous like "CF", or maybe get a little wild
and go all the way for "SD".  But, more often than not, you've simply been
fooled, crushed under the bootheels of incompatibility and told to simply fark
off.

Well, no more.  This little gem of a proglet will solve all your problems, and
end suffering for all of mankind and bring peace and joy to the land.  Or it
could mess you up bigtime, so don't skip reading the rest of this README.
DON'T!  I promise I'll try to make it funny.


WARNING
=======

Here's the quickie warning for those of you who won't read the README.  I know,
you're not reading this for said reason, but at least this way I can point at
you and laugh when you've made a mess of things, because I TOLD YOU SO.

Here's the warning: This software works by unabashedly lying to your Z. It's
unethical, and as always, a little risky.  Specifically:

DO NOT UNINSTALL OR UPGRADE APPLICATION PACKAGES THAT ARE BEING MANAGED BY KTROVE.
All you gotta do is unregister the app from ktrove first, then nobody has to
get hurt.  Just don't forget.


REQUIREMENTS
============

A Zaurus 5500 or equivalent
Optionally, but recommended, Opie-SH: http://www.rit.edu/~tfs1812/#sh


THEORY OF OPERATION
===================

Our trained experts at the BBC (no relation) have learned to synthesize a
substance known to the layperson as "magic pixie dust".  The actual process is
secret (although now involves less suffering by pixies then it used to), so I
can't really tell you any more about that. Instead, here's our cover story.

As it turns out, most applications for the Z can be run from somewhere other
than where they live through the use of this pix... I mean, "symbolic links"

KTrove takes advantage of this by pulling the wool over the eyes of the Z and
copying all of the files that go with a given program somewhere else.  Say...
on your compact flash or SD.  It then provides an easy mechanism to create
and delete the set of symbolic links to make it look like these files are
actually in your main memory.  Except they aren't, so you don't use up (much)
main memory.

Note: some applications won't actually work properly this way (although almost
all do.  I use this to keep an entire web server (apache + mysql) on an SD
card)

Also, this bit about lying to the Z about where it's brains are can lead to
a problem:  If you are in the middle of pulling off this fraud, and you decide
to do something like uninstall or update the application the isn't really
there, things can get mightily confused.  DO NOT UNINSTALL OR UPDATE
APPLICATIONS BEING MANAGED BY KTROVE!  UNREGISTER THEM FIRST!


HOW TO USE THIS BLASTED THING
=============================

Here's the general idea:

1) Install the application you want to manage as normal, on internal RAM. You
   might want to run it, just to be sure it works.
2) Register the application with KTrove.  This moves the application's
   files to the trove location, and out of your internal RAM.
3) Before you use the application, use KTrove to activate it.  This
   sets up the required linkage so your application will run.
4) You can leave applications activated without using much internal
   RAM.
5) When you want to remove the card containing the trove, deactivate
   the applications on the card first.  This removes the linkages,
   and makes the application "disappear".  The card can now be
   removed.
6) If you want to put the application back into your internal RAM, then
   unregister the application from KTrove.  The fiels will be moved
   back, and you can uninstall, update, or do whatever you like with
   them as normal.

NOTE: If, after you register & activate a program, you find it doesn't work
      right - simply unactivate and unregister it.  All should be well, but
      KTrove won't handle your file.  Maybe.  If your'e brave, check the
      "Experts" section below for ways you can jigger it to work.

Here's the specifics:

There are two ways of using KTrove - command line and gui, using the Opie-Sh.
We at the BBC strongly recommend using the gui!  The gui is started by
tapping on the KTrove icon that was installed with the package.  If you don't
have Opie-SH installed, then the installed icon usefully functions as a local
version of TRBBTDDA (http://www.pixelscapes.com/spatulacity/button.htm).


Command Line Operation
======================

For you techno-macho dudes who don't use guis, I'll describe the command line
first.  Type this at the command line, and you'll see a quick command summary:

    ktrove.sh -h

The summary will look something like this:

  /opt/QtPalmtop/bin/ktrove.sh [options]
  A product of the BBC (no relation)
  THIS PROGRAM CAN MESS YOU UP.
  READ THE README.

  [options] is one or more of:
  -a <pgm>  Activate Program
  -c <pgm>  Check Program Status
  -d <pgm>  Deactivate Program
  -g        Use Opie-Sh GUI
  -h        This help message
  -l        List Available Packages
  -r <pgm>  Manage this Program
  -s        Gets the status of the trove.
  -t <path> Use A Trove at <path>
  -u <pgm>  Stop managing this program
  -v        be verbose

If you've read the general idea up earlier, you can probably figure things out
from that.  Here's a blow-by-blow anyhow, in the order you're likely to want
to use the commands.

-t  Sets the trove.

    This options does nothing by itself, but affects the operation of options
    that follow it on the command line.

    The options it affects are: -a -c -d -r -s -u

    By default, all of those options assume that the trove you want to mess
    with is "/mnt/card".  Use -t to change this assumption.  You can specify
    any location you like with -t.  These are the paths you might like to use:

    /mnt/card       This is the SD Card
    /mnt/cf         This is the Compact Flash card
    /home/root      This is internal RAM

    usage example: ktrove.sh -t /mnt/cf -s

-v  Sets verbose mode.

    This makes KTrove tell you what it's doing while it does it.  It only
    affects operations that follow it on the command line.  Maybe you like this
    kind of thing, but the messages are voluminous, so you probably just want
    to never use it.

    usage example: ktrove.sh -v -r <program name>


-l  Lists Available Programs.

    Shows you a list of all the programs you have installed on your Z.
    Whenever KTrove wants a "program name" it means that it wants a name from
    this list.

    Usage: ktrove.sh -l

-s  Gets the Trove Status.

    Shows you a list of all the programs that the specified trove is managing,
    as well as whether they are currently active or not.

    Usage: ktrove.sh -s

-r  Registers a program with the trove.

    Use this to move a program to the trove and begin management.  Once
    registered, the program is not available for use.  You have to activate
    it first.

    Usage: ktrove.sh -r <program name>

-a  Activates a registered program.

    Makes the program available for use.  As a fun little gimmick, you can
    specify the special program name "-ALL-" to make KTrove activate all the
    programs registered with the trove at once.

    Usage: ktrove.sh -a <program name>
    Usage: ktrove.sh -a -ALL-

-d  Deactivates a registered program.

    Makes the program unavailable for use, probably in anticipation of
    unmounting a card or unregistering the program.  You can use the special
    "-ALL-" filename here, too, to deactivate everything all at once.

    usage: ktrove.sh -d <program name>

-u  Unregisters a registered program

    Moves the program back into the location it was in before KTrove messed
    with it in the first place. Do this before uninstalling or updating a
    program.

    usage: ktrove.sh -u <program name>

-c  Check Program Status.

    This is really meant for use when running ktrove from other scripts.  You
    can pass it a program name, and it will return a "0" if the program is not
    activated, and a "1" if it is.

    usage: ktrove.sh -c <program name>

-g  Runs the program under the Opie-SH gui.

    usage: ktrove.sh -g


That's about it!


GUI Operation
=============

This is a much easier way to use KTrove, since you'll be guided through the
data collection visually.  Because this is based on Opie-Sh, and because the
programmers here at the BBC like to do weird things, this gui has a little
bit of a personality.  So, keep in mind two things:

1) It's a bit slow.  Have patience.
2) During normal operation, KTrove will look for all the world like it closed
   down.  It didn't, unless it disappears for longer than a second or so.  In
   that case, something crashed, and you should tell us about it.


Start the gui by either tapping on the KTrove icon or by entering
"ktrove.sh -g" at the command line.

You'll be presented with a screen that tells you what your current trove is,
provides you with a little pull-down box.  This box is your little friend, and
is with you always.  You can drag it around to get it out of the way of text
you want to read.


The pulldown provides a list of commands that echo the comman line parameters
described above, so I'm not going to rehash what they each do here.  You figure
it out.

Oh, and you can always tap the little "x" on the command box to abort whatever
process you accidentally initiated.



Expert Issues
=============

Customizing the file list
-------------------------

When moving files to the trove, KTrove does not move anything in the /lib or
/usr/lib directories, so as to avoid problems with removing libraries that
might be needed by non-managed programs.  Aside from these exceptions, KTrove
manages all the files listed in the ipkg's file list. Also, by default, it only
manages specific files, not entire subdirectories.

You might not want this, exactly.

Sometimes, you might wish that KTrove leave alone a specific file, or
conversely, you might want to add additional files or entire subdirectories
to the trove that weren't part of the original package list.

This can be handy if there's a specific file that won't work when KTroved, but
you want to KTrove the rest of the files, or if you want data directories to
be KTroved along with the application.

There is no user interface to do these things yet.  Until then, you can edit
the control file yourself.  Here's what to do.  Register the program with
KTrove, but leave it inactive (deactivate it if you have activated it).

KTrove makes a subdirectory in the "Trove Directory" (/mnt/card by default),
called "kmnt".  In there, you'll find a subdirectory named the same as your
program, and a file called <yourprogramname>.kctl


To Add Files:

If you want to add additional files to the trove, create a directory path
in the <program> directory that matches where the additional file(s) will live
when activated.  Move (don't copy) the files into the directory you just made,
then add a line into the <yourprogramname>.kctl file that gives the (activated)
path & file name.  The "file" can be an entire subdirectory.

For instance, I have apache-1.3.19-php-4.0.5 KTroved on my SD card, but KTrove
by default does not keep track of my actual website!  To fix this, I located
the directory "/mnt/card/kmnt/apache-1.3.19-php-4.0.5".  By default, apache
wants the website to live in "/home/www/htdocs", so I create that path in
the trove:

mkdir /mnt/card/kmnt/apache-1.3.19-php-4.0.5/home/www/htdocs

And copy my website into the new directory.  Then, I edit the file
"/mnt/card/kmnt/apache-1.3.19-php-4.0.5.kctl" and add the line:

/home/www/htdocs

to the end of it.  That's it!  Now, when you activate apache, a link will
also be created to point apache to the website.  Since the directory itself
is linked in this case, you don't need to add anything from inside the htdocs
directory.

A side effect of this comes around when you unregister the package.  During
unregistration, all of the files that go with the application get moved back
into internal memory.  After this mod, that will include the entire website as
well.  If you have enough memeory available, no problem.  If not, it will fail.


To ignore files:

It's just the reverse of adding.  How'd you guess?  Follow the same rules, but
this time, move the files you want to ignore back to the place they are
supposed to live, rather than in the trove.  Then delete the reference to them
in the kctl file.


Manual Repairs
--------------

It shouldn't happen to someone as awesome as you, but it is just possible that
something could go horribly awry.  If this happens, you probably aren't as
screwed as you might think -- you just need to do a manual reset.  You can get
everything back to its normal (pre-registration) state by hand, like this:

Locate the .kctl file (described in the above section on adding and removing
files) and use it as your guide.

Go through the list in the .kctl and make sure there aren't any stray symlinks
left in the directories specified.  If things went wrong after the program
had been made active, but befor eit had been deactivated, there will probably
be some.  Delete them all, (but be sure they are actually links, and not
actually files).

Now, move all of the files in the trove directory for your program (again, see
above) back to their righful place.  delete the subdir tree for the program in
the trove, and also delete the .kctl file.  In addition, there may be a
hidden file with the .kctl file called ".<program>.activated".  If this exists,
delete it, too.

This should put everything back like it was before you registered the
application.



Support
=======

Didn't you read the disclaimers???

No support is offered or should be expected.  That said, if you were to send
email to zal@babiestastegood.com, you might get blessed with a useful reply
of some sort.  Suggestions are always welcome, too.  Not as welcome as $100
bills, but we'll deal with it.

