How to Make a Master Index

To make a master index for Cheetah, just head on over to this form. If you really want to know how the whole thing works, read the remainer of the current page.

The Remainder of the Current Page

The master index generation program is a KornShell 93 script that lives at the following pathname:

/udir/fscott/BooksInProgress_HTMLandPDF/html/MM.ksh

This script takes one argument, which must be the pathname of a book description file (BDF). The BDF is an ASCII file describing all of the books comprising the master index. Each line of the BDF must have the following format:

directory    four-letter-abbreviation    "Book Title"
...

For example, the complete BDF for Cheetah docs looks as follows:

# CSEE 4.0
Cheetah/admin ADMN Administrator's Guide
Cheetah/user USER User's Guide
Cheetah/architecture ARCH Architecture Guide
Cheetah/developer DVLP Developer's Guide
Cheetah/tagreference TAGS Tag Reference
Cheetah/javaapi JAVA Java API Reference

By the way, the MM.ksh script ignores comment lines (beginning with a #).

Each directory listed in the BDF must contain a realindx.htm file or a link named realindx.htm. The realindx.htm must contain the index for a book. The MM.ksh builds the master index out of all the realindx.htm files.

I'm not going to describe how MM.ksh works. I'll just mention that whenever we change the WebWorks template that produces an index, the MM.ksh file has to be modified.

I just added a front end to MM.ksh. The front end consists of two other pieces of software:

• front_end_to_mm.cgi, which is a simple CGI program that generates the form you see here. This CGI program generates the form by examining file ORG_FILE_REAL.
• MM.cgi, which is the CGI program that gets called when the user presses Build the Master Index. The MM.cgi program generates a subset of ORG_FILE_REAL and places that subset in ORG_FILE. Then MM.cgi invokes MM.ksh.

If you don't want to use the CGI front end, you can simply invoke MM.ksh from a UNIX shell, by doing the following:

1. Log in to a UNIX shell as fscott
2. Change directory to /udir/fscott/BooksInProgress_HTMLandPDF/html by typing:

   
   $ cd /udir/fscott/BooksInProgress_HTMLandPDF/html
   

3. Invoke MM.ksh, specifying the name of a BDF as the sole argument:

   
   $ MM.ksh ORG_FILE_REAL
   

   or

   
   $ MM.ksh MY_CUSTOMIZED_ORG_FILE
   

   The output of MM.ksh is quite cryptic. Sorry about that. the bottom line is that it will typically build the master index without many complaints unless the BDF is bogus.