================================================================================
Trav's Angband Index Linker        Version 1.2              (updated 2005-04-28)
Author: Travis Emmitt                         http://www.tripalot.com/roguelike/
================================================================================

1. Introduction
2. Supported Platforms
3. Supported Variants
4. Installing PERL
5. Creating the Index
6. Linking to the Index
7. Using the Index
8. Support


--------------------------------------------------------------------------------
1. Introduction
--------------------------------------------------------------------------------

TAIL is a PERL script which generates an index of Angband's online help.

It reads in every file in the Angband help tree (except indexes) and then 
generates an index file and several link files, which get saved to a new 
directory called lib\help\index.  

The index file contains a list of terms (lower-case, a-z only), enclosed in 
single quotes.  I try to filter out URLs and filenames.  The link files are 
behind-the-scenes and are used for transitioning from the index to files that 
contain the specified term.


--------------------------------------------------------------------------------
2. Supported Platforms
--------------------------------------------------------------------------------

TAIL should run on any computer with a DOS-like or UNIX-like file system.
I've run it on the following systems:

  - DOS   (as of 1999)
  - UNIX  (as of 1999)  
  - XP    (as of 2005)
  - Linux (as of 2005)

  
--------------------------------------------------------------------------------
3. Supported Variants
--------------------------------------------------------------------------------

TAIL works nicely with:
  - Angband
  - Zangband
  - probably any *band which uses the standard help file format
  
TAIL doesn't work with:  
  - T-O-M-E  (generates help files, which crash the game when you view them!)
  
I think TOME crashes because TOME's help files have a different format from the
other *bands.  If there's demand, I can add support for TOME's help format.

NOTE: It should be completely safe to use TAIL even if the generated index file
crashes your game.  This is because you don't *have* to try to view the index 
from within the game.  If the index crashes your game, simply comment out the 
link to the index (in help.hlp), and (if you want) delete the index files.


--------------------------------------------------------------------------------
4. Installing PERL
--------------------------------------------------------------------------------

TAIL is a PERL script.  This means you need a PERL interpreter.  

If you're running on linux or unix, you probably already PERL installed, so you
can skip this section.

If you're using Windows (e.g., XP), you can grab PERL from www.activestate.com.  

Now, if you're not a programmer, then this might sound intimidating.  Even if 
you're a geek like me, it might seem like overkill to install an interpreter 
just for one program (of questionable utility).

I feel the same way.  If I saw "TAIL" listed on someone else's website, there's 
very little chance I would bother to download it and PERL.  Even if I already
had PERL installed, I probably wouldn't download someone's PERL script.  But
that's me.  You might be more curious than I am.

Anyway, if you grab the ActiveState version of PERL, you will notice that it
installs a *ton* of files.  I found that I can delete most of them and still 
have PERL run.  Here's the ones I deleted:

(in c:\perl)
  html -- everything
  lib  -- everything
  site -- everything
  bin  -- everything except:
    *.exe
    *.dll
    *.cfg

This shrinks PERL's "footprint" on your PC.  Of course, if you actually want to
be able to read all the PERL help files and access to all the PERL modules, then
you probably don't want to delete anything.  Try zipping stuff as a compromise.


--------------------------------------------------------------------------------
5. Creating the Index
--------------------------------------------------------------------------------

Okay, time to actually *do* something!

In DOS I just cd to angband\lib\help and type:

  perl tail.pl .

In UNIX I do the same thing but I add "UNIX" as another argument:

  perl tail.pl . UNIX
  
Make sure tail.pl is in your path, or else include its path:

  perl c:\scripts\tail\tail.pl 
  perl ~/downloads/tail/tail.pl . UNIX

To see a quick help page type:

  perl tail.pl

If you have problems running tail.pl, take a look at the source code.  It's not
a complete mess, so it shouldn't be too hard to hack it to make it work.

If you're stumped, contact me and I'll throw together some instructions:

  http://www.tripalot.com/contact/

I'll add robustness after I get convinced people other than me are actually 
using it!  Even though TAIL has been available for over 6 years, I don't think
I have ever received an email about it.  Maybe no one uses it except me.  Heck,
even I don't use it very often, since my Roguelike game playing is so sporatic.


--------------------------------------------------------------------------------
6. Linking to the Index
--------------------------------------------------------------------------------

You'll need to edit your help.hlp to include a link to index/index.hlp.

I added a message to tail.pl that tells you what to add:
      
      ===================================================================
      In order to access the index from within the game, you'll need to
      edit lib\help\help.hlp.  You only need to do this once.
      
      1) Decide what key will display the index.
         -- e.g., I chose 'x'
         -- make sure no other help items use this key
      
      2) Add a line to help.hlp telling the user how to open the index.
         -- e.g., (x) Index (index/index.hlp)
         -- you should mimic the style of the help for consistency
      
      3) Add a line to help.hlp telling the game how to open the index.
         -- e.g., ***** [x] index/index.hlp
         -- make sure the ***** starts the line
         -- try putting this line after the other ***** lines
      
      4) Start the game, hit '?' for help, and see if the index works.
         Good luck!
      ===================================================================

Hopefully, that makes sense.  I'll just emphasize that it's a one-time edit.
You don't need to do edit help.hlp each time you run TAIL.  

The reason I don't have TAIL update the help file is I don't want to change any
of your files; I want TAIL to be a "safe" utility to run.  It creates files, but
does not modify existing files.


--------------------------------------------------------------------------------
7. Using the Index
--------------------------------------------------------------------------------

1) Start your game.  
2) Open help (usually via "?").  
3) Hit the key that links to the index ("x" in my example above).

   You should now be viewing the index.  
  
   If the game crashes, it probably uses a different help format (e.g., TOME).  
   Simply remove the links you added in part 6 and try another variant.

4) Use the search feature to jump to a specific term.

   For example, if you want to find out where "sword" is mentioned *anywhere* in 
   the help system, type:
  
       /sword    

5) Enclose your term in quotes (e.g., /'sword') if you want to ignore other 
   words which contain "sword" (e.g., "password").

6) Use the specified key combos to get to the appropriate page.

   If you searched for "frodo", you'll see something like this:

       'frodo' [62] misc/tolkien.txt    2
               [32] chars/hobbits.txt   1

   This means there are two occurances of "frodo" in misc/tolkien.txt and one in 
   chars/hobbits.txt.  
  
   To view misc/tolkien.txt,  hit "6" and then "2".
   To view chars/hobbits.txt, hit "3" and then "2".  
  
7) Once you are on the appropriate page, you can type "/worm" again to search 
   for the term you specified.

That's it.  It's not fancy, but should help you locate parts of the Angband
help system more quickly than if you didn't have an index installed.


--------------------------------------------------------------------------------
8. Support
--------------------------------------------------------------------------------

To download the latest version of TAIL:
  
  http://www.tripalot.com/roguelike/download.htm

To discuss TAIL publicly:
  
  http://www.tripalot.com/roguelike/list/list.htm

To send me a private email about TAIL:

  http://www.tripalot.com/contact/?subject=TAIL


================================================================================
Author: Travis Emmitt                         http://www.tripalot.com/roguelike/
================================================================================
