.\" masterindex .de Ps .nf .ft CW .sp .5 .ps 9 .. .de Pe .ps 10 .fi .ft R .sp .5 .. .TH masterindex "30 November 1989" .SH NAME masterindex \- indexing program for single and multi-volume indexing. .SH SYNOPSIS .B masterindex [ .B \-master [ .I " volume" ]] [ .B \-page ] [ .B \-screen ] [ .IR filename ".\|.\|. ]" .SH DESCRIPTION \f(CWmasterindex\fP generates a formatted index based on structured index entries output by \f(CWtroff\fR. Unless you re-direct output, it comes to the screen. .SH OPTIONS .TP .B \-m or \f(CW-master\fP indicates that you are compiling a multi-volume index. The index entries for each volume should be in a single file and the filenames should be listed in sequence. If the first file is not the first volume, then specify the volume number as a separate argument. The volume number is converted to a Roman numeral and pre-pended to all the pages numbers of entries in that file. .TP .B \-p or \f(CW-page\fP produces a listing of index entries for each page number. It can be used to proof the entries against hard copy. .TP .B \-s or \f(CW-screen\fP specifies that the unformatted index will be viewed on the "screen". The default is to prepare output that contains \f(CWtroff\fR macros for formatting. .SH "Background Details" Tim recommends \fIThe Joy of Cooking\fP index as an ideal index. I examined the "JofC" index quite thoroughly and set out to write a new indexing program that duplicated its features. I did not wholly duplicate the JofC format as well but this could be done fairly easily if it is ever desired. Please look at the JofC index yourself to examine its features. .PP I also tried to do a few other things to improve on the previous index program and provide more support for the person coding the index. .SH "Coding Index Entries" This section describes the coding of index entries in the document file. We use the \&.XX macro for placing index entries in a file. The simplest case is: .Ps \&.XX "entry" .Pe If the entry consists of primary and secondary sort keys, then we can code it as: .Ps \&.XX "primary, secondary" .Pe A comma delimits the two keys. We also have a \&.XN macro for generating "See" references without a page number. It is specified as: .Ps \&.XN "entry (See anotherEntry)" .Pe While these coding forms continue to work as they have, \f(CWmasterindex\fP provides greater flexibility: it allows three levels of keys: primary, secondary and tertiary. You'd specify the entry like so: .Ps \&.XX "primary: secondary; tertiary" .Pe Note that the comma is not used as a delimiter. A colon delimits the primary and secondary entry and the semicolon delimits the secondary and tertiary entry. This means that commas can be a part of key using this syntax. Don't worry, though, you can continue to use a comma to delimit the primary and secondary keys. (Be aware that the first comma in a line is converted to a colon, if no colon delimiter is found.) I'd recommend that new books be coded using the above syntax, even if you are only specifying a primary and secondary key. .LP Another feature is automatic rotation of primary and secondary keys if a tilde (~) is used as the delimiter. Thus, the following entry .Ps \&.XX "cat~command" .Pe is equivalent to the following two entries: .Ps \&.XX "cat command" \&.XX "command: cat" .Pe You can think of the secondary key as a classification (command, attribute, function, etc.) of the primary entry. Be careful not to reverse the two, as "command cat" does not make much sense. To use a tilde in an entry, enter "~~". .LP I added a new macro XB that is the same as .XX except that the page number for this index entry will be output in bold to indicate that it is the most significant page number in a range. .Ps \&.XB "cat command" .Pe When \f(CWtroff\fR processes the index entries, it outputs the page number followed by an asterisk. This is how it appears when output is seen in screen format. When coded for \f(CWtroff\fR formatting, the page number is surrounded by the bold font change escape sequences. By the way, in the JofC index, I noticed that they allowed having the same page number in Roman and in Bold. Also, this page number will not be combined in a range of consecutive numbers. .LP One other feature of the JofC index is that the very first secondary key appears on the same line with the primary key. The old index program placed any secondary key on the next line. The one advantage of doing it the JofC way is that entries containing only one secondary key will be output on the same line and look much better. Thus, you'd have "line justification, definition of" rather than having "definition of" indented on the next line. The next secondary key would be indented. Note that if the primary key exists as a separate entry (it has page numbers associated with it), the page references for the primary key will be output on the same line and the first secondary entry will be output on the next line. .LP To re-iterate, while the syntax of the three-level entries is different, the index entry .Ps \&.XX "line justification, definition of" .Pe is perfectly valid and produces the same result as .Ps \&.XX "line justification: definition of" .Pe (The colon disappears in the output.) Similarly, you could write an entry, such as .Ps \&.XX "justification, lines, defined" .Pe or .Ps \&.XX "justification: lines, defined" .Pe where the comma between "lines" and "defined" does not serve as a delimiter but is part of the secondary key. .LP The previous example could be written as an entry with three levels. .Ps \&.XX "justification: lines; defined" .Pe where the semicolon delimits the tertiary key. The semicolon is output with the key and multiple tertiary keys may follow immediately after the secondary key. .LP The main thing, though, is that page numbers are collected for all primary, secondary, and tertiary keys. Thus, you could have output such as: .sp .in +4n justification 4-9 lines 4,6; defined, 5 .in -4n .sp .SH "Sorting" One advantage of the new syntax is that sorting is more reliable. The old program included the comma in the sort key, so you'd get anomalies in the sort. The sort program was looking at the entry as a whole sequence, not really performing sorts based on the primary and secondary keys. If this doesn't make sense to you, well, then, just take it for granted. .SH "Output Format" One thing I wanted to do that our previous program did not do is generate an index without the \f(CWtroff\fR codes. \f(CWmasterindex\fP has 3 output modes: \f(CWtroff\fR, screen and page. .LP The default output is intended for processing by \f(CWtroff\fR (via \f(CWfmt\fP). It contains macros that are defined in \fI/work/macros/current/indexmacs\fP. These macros should produce the same index format as before, which was largely done directly through \f(CWtroff\fR requests. Here's a few lines off the top: .Ps $ \f(CBmasterindex ch01\fP \&.so /work/macros/current/indexmacs \&.Se "" "Index" \&.XC \&.XF A "A" \&.XF 1 "applications, structure of 2; program 1" \&.XF 1 "attribute, WIN_CONSUME_KBD_EVENTS 13" \&.XF 2 "WIN_CONSUME_PICK_EVENTS 13" \&.XF 2 "WIN_NOTIFY_EVENT_PROC 13" \&.XF 2 "XV_ERROR_PROC 14" \&.XF 2 "XV_INIT_ARGC_PTR_ARGV 5,6" .Pe The top two lines should be obvious. The \f(CW.XC\fP macro produces multi-column output. (It will print out in two columns for smaller books the page width is 's not smart enough to take arguments specifying the width of columns but that should be done.) The \f(CW.XF\fP macro has 3 possible values for its first argument. An "A" indicates that the second argument is a letter of the alphabet that should be output as a divider. A "1" indicates that the second argument contains a primary entry. A "2" indicates that the entry begins with a secondary entry, which is indented. .LP When invoked with the \f(CW-s\fP argument, the program prepares the index for viewing on the screen (or printing as an ASCII file). Again, here are a few lines: .Ps $ \f(CBmasterindex -s ch01\fP A applications, structure of 2; program 1 attribute, WIN_CONSUME_KBD_EVENTS 13 WIN_CONSUME_PICK_EVENTS 13 WIN_NOTIFY_EVENT_PROC 13 XV_ERROR_PROC 14 XV_INIT_ARGC_PTR_ARGV 5,6 XV_INIT_ARGS 6 XV_USAGE_PROC 6 .Pe Obviously, this is useful for quickly proofing the index. The third type of format is also used for proofing the index. Invoked using \f(CW-p\fP, it provides a page-by-page listing of the index entries. .Ps $ \f(CBmasterindex -p ch01\fP Page 1 structure of XView applications applications, structure of; program XView applications XView applications, structure of XView interface compiling XView programs XView, compiling programs Page 2 XView libraries .Pe .SH "Compiling a Master Index" A multi-volume master index is invoked by specifying \f(CW-m\fP option. Each set of index entries for a particular volume must be placed in a separate file. .Ps $ \f(CBmasterindex -m -s book1 book2 book3\fP xv_init() procedure II: 4; III: 5 XV_INIT_ARGC_PTR_ARGV attribute II: 5,6 XV_INIT_ARGS attribute I: 6 .Pe Files must be specified in consecutive order. If the first file is not Volume 1, you can specify the number as an argument. .Ps $ \f(CBmasterindex -m 4 -s book4 book5 \fP .Pe .SH FILES .PD 0 .TP 20 .B /work/bin/masterindex .B /work/bin/romanum .B /work/bin/pagenums.idx .B /work/bin/combine.idx .B /work/bin/format.idx .B /work/bin/page.idx .B /work/bin/rotate.idx .B /work/macros/current/indexmacs .PD .SH "SEE ALSO" Note that these programs require "nawk" (new awk). .BR nawk (1), .BR sed (1V) .SH BUGS The new index program is modular, invoking a series of smaller programs. This should allow me to connect different modules to implement new features as well as isolate and fix problems more easily. .LP Index entries should not contain any \f(CWtroff\fR font changes. The program does not handle them.