IDX 1

NAME

Idx − make and manipulate index files.

SYNOPSIS

@BINDIR@/idx [−dhmprtw] file

DESCRIPTION

Idx is an helper tool to make and to manipulate index files. Idx has been made to automatically index troff document, but it can also be used manually, to make an index of a book.

OPTIONS

• −d: Take troff output in entry, and output an index in a troff format. Internally used by troff macros to build indexes. This is the default.
• −h: Print a short help.
• −m: Mix all lines in a single line.
• −p: Take a list of words in entry, and output a list of pages.
• −r: Reformat a list of words to fix errors.
• −t: Take a list of pages in entry, and output an index in a troff format.
• −w: Take a list of pages in entry, and output a list of words.

FORMAT

There are four format of index file that Idx can work with: a list of pages, a list of words, troff output and troff input.

List of pages

A list of pages indicates which words appears on a page. Each line of a list of pages is formatted as follow:

• page number,
• two semi-colons followed by one space (:: ),
• a list of words separated by a comma and a space (, ).

Example:

33:: troff, refer, index
34:: troff, index, nroff
35:: index, unix, refer

List of words

A list of words indicates in which pages appears a word. Each line of a list of words is formatted as follow:

• the word,
• two semi-colons followed by one space (:: ),
• a list of page number or range of pages separated by a comma and a space (, ). A range of page is made by two page number separated by a tiret (-).

The previous example would be formatted as follow:

index:: 33−35
nroff:: 34
refer:: 33, 35
troff:: 33
unix:: 35

Troff output

When idx is used to index a troff document, the output produced by troff and passed to idx should be as follow:

• A single letter key which indicate what the index is about (W for index of words, T for index of titles...),
• A ">" followed by a space (> ),
• The indexed word,
• Two semicolons followed by a space (:: ),
• The page number where this word appears.

The previous example should be formatted as follow:

W> troff:: 33
W> refer:: 33
W> index:: 33
W> troff:: 34
W> index:: 33
W> nroff:: 34
W> index:: 35
W> unix:: 35
W> refer:: 35

Troff input

Idx can format an index so that troff can print it correctly. The format of troff input is as follow:

.K<                  \" one letter keyword defining the index
.ds <P x, m−n    \" list of pages
.K> word             \" the word which appears on these pages

So, a troff macro that use idx should define the following macros:

• K<: Start an index of type K. Usually, such a macro will print a title, such as "Index of words".
• K>: Print the index entry defined as argument, followed by the list of pages previously defined by the <P string. You should add a dot at the end of the list of pages, since idx will not add it.

EXAMPLE

This example taken from real life will show how to print an index of a paper book.

• Read the book, and, annotate it to underline the words you’ll have to index.
• On a file of your computer, write an index formatted as a list of pages: for each page of the book, write the words it contains.
• Use idx to translate this file to a sorted list of words:

idx −w a.idx > b.idx

• You should read this list of words, since you’ll probably have to correct some mistakes, or rename some index entry.
• Once done, reformat it with idx:

idx −r b.idx > c.idx

• Use idx to pass this formatted index to troff:

idx −t c.idx | troff | dpost > index.ps

FILES

@BINDIR@/idx

SEE ALSO

utmac(7)

LICENSE

Idx and this man page are distributed under the isc license

AUTHOR

Written by Pierre-Jean Fichet.