Converting Indexes with WebWorks Publisher

While WebWorks Publisher (WWP) 7.0 can convert FrameMaker indexes into different online formats, getting things to work initially can be a bit of a challenge. Page ranges in index entries result in hyperlinks to both the starting and ending locations. Index hyperlinks don’t always link to the top of a help topic, but often to somewhere in the middle. For Simple HTML and Dynamic HTML, “See” and “See also” references can fail to convert altogether. However, if you do get stuck, Customer Support can help pull you through.

Page Ranges

Page ranges represent a significant issue. In print indexes, the page range gives a rough indication of whether there’s a little or a lot of material. Unfortunately, WWP mindlessly converts the ending page references to hyperlinks because WWP lacks any means for identifying a page range. To deal with this problem, you can either

not use page ranges at all, or
use a workaround in FrameMaker

To work around the problem in FrameMaker, before every <$startrange> index marker enter a simple index entry with the same index marker text, but without the <$startrange> coding. The start of every range will thus have two index markers: a simple index marker and a marker indicating the start of an index range. You will also need to change the line in the index reference page that reads <$pagenum> to <$autorange><$pagenum>. This change prevents the starting page numbers from appearing twice. Before you convert your document using WWP, simply delete all markers containing <$startrange> or <$endrange>.

Index Hyperlinks

In print and PDF indexes, you want the index markers to be in the exact place on the page where the index topic begins (or ends). But in online help, it’s preferable that the index hyperlink goes to the top of the help topic rather than to somewhere in the middle. If you link directly to the middle of a help topic, the user can easily become disoriented. WWP always links to where the original index marker was placed in the FrameMaker document—not necessarily to the top of the help topic. This issue can be addressed in Simple HTML, Dynamic HTML and HTML Help using another workaround.

This workaround removes the portion of the hyperlink that points to the specific target within an HTML file, leaving the hyperlink to point to the top of the HTML file. Using FrameMaker, open the compiled index file in the Output folder. Replace html#wp* with html for All using Wildcards. Save as a text file. The index hyperlinks will now point to the tops of the HTML topic files. Unfortunately, this approach won’t also work for Java Help.

“See” and “See also” references

“See” and “See also” references can fail to compile in Simple HTML and Dynamic HTML. This problem occurs because WWP needs to be told explicitly how to identify “See” and “See also” references. You need to enter the following macro code:

$COMMENT(Specify patterns that indicate see/see also index entries.);\
$IF_EXISTS($DATA(raw)["See |See also "];,TRUE);

To enter this macro code, choose Designer from the Style menu. Click on the User Macros tab. Click the New button and name the new macro, UMSeeAlsoFilter. Set the macro to the above code, adjusting the “See |See also ” text as necessary. Click Apply.

Click on the Building Blocks tab. Then locate the macro named BP70ParaMacroContent_Data. Locate the following line:

$LINKHEADER;$LINKDATA(UMLevelIXFormat);,

Replace this line with

$IF_EQUAL($UMSeeAlsoFilter;,TRUE,$DATA["<a [^>]*>|</a>",""];,
$LINKHEADER;$LINKDATA(UMLevelIXFormat););,

Click OK. Choose Save from the File menu and save your project.

You can choose to use symbols or page titles for the index hyperlinks instead of the default sequence numbers by making changes to the UMLevelIXFormat macro. In Dynamic HTML, ensure that the document.css file formats the index correctly—in both Internet Explorer and Netscape Navigator.

WWP Customer Support

When evaluating WWP, Customer Support was an invaluable resource in getting my index to convert into Simple HTML, Dynamic HTML, HTML Help and Java Help (all the formats that I tested). WWP online help was useful, but not always fully up-to-date.

With some nudging, WWP can do a nice job converting your FrameMaker indexes to a variety of online formats.

Fred Brown
Allegro Technical Indexing
fred.brown@allegrotechindexing.com
(613) 728-9373

June, 2002
Allegro Time!