*** Ballad Index Macintosh Installation Instructions ***

FOR OS X Macintoshes.

To you experienced Macintosh users, this is going to sound terribly
primitive. Remember, this software runs, essentially without modifications,
on unix systems. This is a unix program, very slightly prettied-up for
Mac.

So: There is no installer. You have to install yourself.

PLEASE NOTE: Because it's unix, UPPER and lower case matter, as do
exact spelling. Be sure to use the exact names shown below.

*** System Requirements ***

Any Macintosh running OS X 10.3 or higher. (Technically,
you can run the software in OS X 10.2, but you have to run it from the
unix command line; it cannot be run from the desktop. If you have 10.2,
it's probably easier to use the Classic ballad index software.)

The Index requires about 15 MB of available disk space, and must be run on
a writeable volume.

*** Installation Instructions ***

Installing the Ballad Index consists of installing the software itself
and the data files. These can be installed separately (the software will
be updated only rarely, the data much more frequently).

To install the software, simply create the folder "BalladIndex," containing
the enclosed program "BalladIndex," plus the auxiliary files "BDIDXHLP.HLP"
and "KEYWORDS.TXT," in your Applications folder (in the top directory on
your hard disk).

Next, place the unix version of the Ballad Index data file (BALLDIDX.TXT,
using line feed breaks) in the same folder. (NOTE: Do NOT use the version
for OS 9 Macintoshes; it WILL NOT WORK.) If you wish to use the Supplemental
Tradition, you must also include that file, under the name supptrad.txt.

Once you have done these two things, the Ballad Index is ready to run.
Just double-click on the BalladIndex icon, and you're off.

IMPORTANT: The file names here matter. The Index database must be named
BALLDIDX.TXT -- note the ALL CAPS. Similarly, the folder containing it
must be named BalladIndex, not BALLADINDEX or Ballad Index Folder or anything
else. Different decompression utilities may change these names. If they do,
put them back. The correct names for the files are

BalladIndex (you can change this one if you like)
BALLDIDX.TXT   (the data file -- many megabytes)
BDIDXHLP.HLP
KEYWORDS.TXT
supptrad.txt

These files will normally be distributed in three different archives:
One containing this software (which you probably already have), one
containing BALLDIDX.TXT, and one containing supptrad.txt. When you
download them, be sure that you get the correct versions for OS X
Macintosh -- and be sure that you use a decompression utility which
does not change the line breaks.

Also, the Index must be installed by someone with Administrator access.
If you are the only user of your Mac, that's probably you. If you aren't
the sole user, you may need the help of the Administrator (probably person
who first used and set up your Mac). Have this person install the files
in the Applications folder, and run the Index the first time. This is
needed to create the auxiliary Index files.

*** Convenience Notes ***

The Ballad Index will run, more or less, if you simply follow the
installation instructions outlined above. But, as you may have noticed,
it runs in the Terminal window (unix command line). It isn't pretty at
all, but it works.

You can make it work a little better by customizing your terminal
settings. You can enable the following features:

* Make Command Q work to quit the program:
  Before doing this, be ABSOLUTELY SURE you are not running the Ballad
  Index in Terminal. Launch Terminal (in the Utilities folder inside the
  Applications folder) but DO NOT run the Ballad Index. If the Ballad
  Index is running, you may cause Terminal to become unable to run anything
  else!

  In Terminal, go to "Window Settings...." on the "Terminal" menu. A
  preferences panel ("Terminal Inspector") will open. There is a menu at
  the top, which should read "Shell." In the middle of the panel is a set
  of radio buttons, labelled "When the shell exits." Choose either "Close
  the window" or "Close only if the shell exited cleanly." Then click
  "Use Settings as Defaults" at the bottom of the pane.

  Go to the popup menu at the top, and choose "Processes." The preferences
  panel will change. In the bottom half is a set of radio buttons that says
  "Prompt before closing window." Choose either the radio button that says
  "Never"  or (better) the button that says "If there are processes other
  than...." Below this there is a list of programs. Click the "Add" button.
  A line will appear in the list labelled "new_command." Double-click on
  this and type in "bi". Then "Add" another line, and replace this new
  "new_command" with "BalladIndex" Finish by clicking "Use Settings as Defaults"
  again.
  
  Close the Terminal inspector, and quit Terminal, without running the
  Ballad Index, to save the preferences.

* Run the program in a larger window.
  The Terminal window, if not customized, will open to a small window of
  24 lines, 80 columns. This is workable, but small. You can improve this
  by changing the default size of the Terminal window.
  
  You may change these settings while running the Ballad Index, or while
  simply running Terminal. On the Terminal menu, go to "Window Settings...."
  The "Terminal Inspector" panel opens. The popup menu at the top will
  probably read "Shell." Pull it down to "Window." The first item is
  "Dimensions." There is an item for Columns and another for Rows. Put
  in numbers to produce a comfortable window (I prefer 120 columns, 40
  rows), then click "Use Settings As Defaults." (Note: I've found
  that it helps to change the settings, save the defaults, and then
  go to another settings panel and fiddle. Terminal sometimes forgets
  if you don't do this.)
  
  Close the Terminal inspector. You will have your larger settings the
  next time you run the Ballad Index.

* Put the Ballad Index icon in the Dock.
  Although the Index "looks like" a Mac program, in fact it is not; it's
  a command line program. That means you can't put it in the Dock among
  your ordinary programs.
  
  That doesn't mean you can't install it in the Dock, though. The Dock
  is actually divided into two parts: Programs, and documents, with a
  line between them. You can put the Ballad Index in the Dock on the
  documents side. That's the side where the trash icon is found.