================================================================================ 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/ ================================================================================