Let's face it -- indexing can be painful. The process is often put off until the end of a project, and by then it's likely that not enough time remains to do the kind of job you'd like. And the nagging question remains: does anyone really use an index?
Yes, we all do. And, virtually any document can benefit from some sort of index. One good "find" in an index that saves your reader frustration makes that index worth the effort.
The purpose of an index is simple:
|
Lead readers to the detailed information they seek through a list of keywords and phrases, permutations, synonyms, and other references in that list. |
We've all been irritated by documents without indexes; or worse, indexes that sent us on wild goose chases or failed to point to the area we really needed. How do bad indexes happen? That's a broad question with many answers. But from our experience poor indexes often happen when the person or group creating the index is overloaded by the task.
How does such a seemingly simple task become so demanding? One key issue is the amount of time indexing can take.
|
Whether generating or maintaining, indexing can be a slow and often incomplete task. |
If we analyze why this is so, we find two main culprits. One is mechanics -- how the index is assembled. The other is the craft of indexing -- how we decide what to index, how entries are interrelated, how we choose synonyms, and so on.
In terms of mechanics, indexing in FrameMaker is greatly simplified and accelerated using the IXgen tools described in this white paper.
In terms of craft, we've observed that when the mechanical aspects are improved, much more time and energy can be devoted to that craft, even by those with little experience. When no time exists to generate an index using traditional FrameMaker methods, IXgen lets you quickly create a simple but useful index.
What needs to be indexed? Probably any document over five pages could benefit from some sort of topical pointer system, whether it's a table of contents, an index, or hypertext links. This of course includes:
The list is nearly as long as there are types of documents.
|
Not only does a good index serve print readers, a good index -- or even a specialized secondary index -- is vital for successful on-line documentation. |
Now we come again to the question of staff resources. Which engineer, technical writer, report author, or researcher has time to do their own index using traditional methods? Not many. Any available time must be leveraged. You'll see how IXgen can do this as we go on.
In many cases, the ideal index would be created as part of the authoring process. Until now, there was no effective way to integrate writing and index creation in FrameMaker.
In a few simple steps, how do you create and maintain a good index?
At one time, the FrameMaker marker window was adequate for simple marker placement and maintenance. But as indexes demand more sophistication this interface becomes too slow and is usually not practical. More comprehensive indexes are often built from large numbers of markers, and require on-going maintenance as a document evolves.
The FrameMaker marker window approach for larger indexing is costly. The best possible index may never be created because it's too difficult using the marker window. And, to compound the problem, updates to the main body of a document may never get properly reflected into the index markers. Once again, the marker window interface is too narrow to let you quickly and easily apply main source updates to marker text.
IXgen is a completely new interface to the FrameMaker marker system. This new interface consists of a number of tools to make marker manipulation direct and simple. The next tables introduce the IXgen tool set and classify tool applications. Later portions of this white paper describe the IXgen tools in more detail, along with some typical uses.
| IXgen Tool | Description |
|---|---|
|
Apply edited marker list back to source markers (includes the Split and Permute options) |
|
| Application | IXgen Tool |
|---|---|
(Detailed tool descriptions begin in the IXgen Toolset Summary section.)
Use IXgen for these applications:
Looks like I'll only use IXgen whenever I do indexing -- maybe a couple of times a year. How can I justify buying a tool that will have such little use?
Part of our mission is to show how -- with the right tool -- indexing can easily be an ongoing process. The overall quality of your documents can benefit by making indexing part of the daily writing process.
IXgen facilitates this kind of daily marker interaction in a way that's virtually invisible to the writer. Indexing and index maintenance can be as immediate as spell checking, proof-reading, formatting, or any other activity. Indexing can even happen while text is being created. This is important, because only IXgen is capable of providing this level of support.
Still, I wonder just how much use these tools will get.
Remember, IXgen can work on any marker type, not just Index markers. This opens a number of possibilities in working with other types of markers and performing tasks not even related to indexing, such as deleting unwanted conditional text. or inserting hypertext commands.
Okay. BOTTOM LINE: How much time can I really save with IXgen? How can I pay for IXgen licenses?
As an example, let's use a 300 page document spread across 10 chapters. Consider doing the most basic indexing task: indexing each chapter head and each first and second level head. That's a lot of mouse movement, clicking, and trips to the marker window. Shall we say three hours? Maybe four hours? Five? IXgen can do the same thing in a few minutes .
But at this first step, you've got a rather poor index, by any standard. What about making some typical variants of those entries? If you had energy left over from creating these markers using just the standard FrameMaker marker window, you'd need at least another two or three hours to permute those markers. Use IXgen to intelligently permute the entries in a few seconds .
What about the inevitable variations in capitalization, particularly following a permutation? Plan on at least another two hours to correct these by hand; IXgen can do it in seconds .
What about "specials" and "tweaks" -- in other words, how much time do you spend polishing the index? Where should you add the "see also's"? The page ranges? Doing it manually can run into many more hours. With IXgen, you can polish in minutes , not hours.
It's fair to say that with a 300 page document you can do a good start-to-finish index in less than an hour using IXgen. The same index done manually could take 15 hours or more. As you add layers of sophistication and completeness to the index, the time differences to simply manipulate the markers to improve the index become even more pronounced.
Two writers, using two IXgen seats, can more than pay for those seats in a single day of use from the time saved. Here's how we figure this:
Assume a competent, medium-scale writer is worth $25/hour, gross pay, including benefits and other non-direct compensation items. If 28 hours are saved between two writers, that's $700.00. If you create only three documents like this each year, that's $2100. Two IXgen UNIX seats in total cost only $418. (Two IXgen 7 Windows seats are $398.)
In this very simple scenario, you've picked up $1600. Your savings will most certainly be much higher, because we're illustrating a minimal-use case.
Also consider these items in terms of their additional value:
Who besides writers can use IXgen?
Anyone who creates a document (even a small one) -- where an index of any kind would be a good feature to add -- can use IXgen.
Anywhere you use FrameMaker is probably a good place to use IXgen. And because IXgen is implemented using the Frame API, IXgen "looks and feels" just like FrameMaker because it is part of FrameMaker. This makes IXgen very simple to use even for those who only occasionally use FrameMaker.
Do documents processed by IXgen have to be read by systems where IXgen is installed?
No! Remember, IXgen is a marker system interface. IXgen does not change the underlying marker or document structure. Therefore, documents processed with IXgen remain true FrameMaker documents -- nothing more, nothing less. All you've done with IXgen is greatly simplify the process of adding and maintaining markers.
Note that IXgen can process any marker type. You are not restricted to index markers. This opens up some interesting possibilities.
Windows 95, NT, 3.1x, Solaris, and SunOS demo copies of IXgen are available for downloading from our web page. Go to this URL:
http://www.pacifier.com/~franks
Select the IXgen option and follow the instructions there for downloading, installation, and obtaining a demonstration password.
If you don't have web access, give us a call. We'll be happy to mail you a demonstration package on a diskette.
IXgen consists of the following tools. Note that these tools can be used in virtually any sequence you'd like. A "normal" sequence depends on the task at hand. The next table shows "typical" usage sequences based on two scenarios: creating an index from scratch and maintaining an index.
Of course, you are not locked into any particular usage sequence. Use the tools as needed in any logical order. (You won't get much value from the maintenance-oriented IXgen tools unless markers are present. So, you'd want to start by creating markers, either manually or automatically by using Markers from Keywords or Markers from Tags .)
IXgen tools can operate on a highlighted area of a document, an entire document file, or from the book level (all documents in the book are processed). This selectivity lets you optimize IXgen usage for specific tasks, such as initial bulk creation of markers to touch-up maintenance and marker additions for new text blocks.
Generate editable list of markers
|
Apply edited marker list back to source markers (includes the Split and Permute options)
|
When Apply Edited Marker List is selected, two optional apply functions are available. The first option, Split multiple index entries into separate markers , is discussed here. The second, Permute (rotate) marker text , is explained in the next section.
To select Split multiple index entries into separate markers , click the option button in the dialog box which appears when Apply Edited Marker List is called.
FrameMaker supports multiple index entries per marker. Individual entries are delimited with a semicolon. If you select Split multiple index entries into separate markers, IXgen will check each marker for multiple entries. (Multiple index entries are separated by semicolons within the marker string.) If found, new markers are created as needed so that only one index entry appears in each marker.
Some people find the one entry/one marker approach easier to understand; other people prefer to have related entries in one marker. IXgen simply provides a means to split multiple entry markers. Note that once split, there is no "recombine" utility. Also note that a marker entry has a 255 character limit (imposed by FrameMaker), so the split function can be used to assure the maximum possible marker space for long or complex entries.
A generally useful indexing technique is to do a circular rotation of the word order of an entry. A new entry is created with each rotation. For example, this phrase:
could be rotated twice to produce two new additional entries:
brown, fox quick
fox, quick brown
To more clearly see the pattern consider this abstract example:
ff, aa bb cc dd ee
ee ff, aa bb cc dd
dd ee ff, aa bb cc
cc dd ee ff, aa bb
bb cc dd ee ff, aa
To minimize nonsensical, confusing, and useless rotations, IXgen follows some basic rules and offers permutation controls (discussed next). Here are the basic rotation rules:
Control list files are provided so that you can extend the definition of what might be considered a "nonsense" rotation in your environment. For example, you can list words or phrase that if found in the marker, mean that the marker should not be rotated. Also, you can list words or phrases that become "atoms" and should not have any rotation points in them, but these can be rotated among other words as if they were a single word.
Place marker text in main body text
|
Return expanded marker text to markers
|
Generate new markers by searching for keywords
|
Generate new markers from selected para tags
|
Other tools from FSA include FM2A (FrameMaker to ASCII), and PEK (Programmable Export Kit) for FM2A. FM2A extracts the text of a FrameMaker document and outputs a formatted ASCII version of that FrameMaker file. PEK extends this function by providing a number of points where control sequences for a target text processing system (such as HTML or LaTeX) can be inserted.
FSA has been creating popular add-on productivity tools for FrameMaker since 1990.
