Chapter 4. External Cross References and Multiple Link Targets

This chapter explains how to create and test external cross references and how to find and fix multiple link targets.

Creating Cross-Reference Links to Other Books

This section includes the following:

Using Markers to Create an External Book Link

Use the method described in this section to create a cross-book link to another book using the FrameMaker Marker tool. Note that you can use this procedure only with target books for which you have SGML source files.

To create a cross-book link using markers:

  1. Open the FrameMaker chapter in your book and insert the cursor at the beginning of the text where the cross-book link marker will be placed.

  2. Go to the FrameMaker menu bar and select Select > Marker.

  3. In the Marker dialog, select Type 18 from the Marker Type popup menu.

  4. In the Marker Text box, enter information about the cross-book link using this syntax:


    target_short_title is the short title of the target book, and unique_id is the identifying number associated with the target element in the target book. To identify the correct unique_id, look in the SGML file for the target book; find the target element and look for an <XREFTARGET> tag nearby. For instance, in the following example the unique_id for the TITLE element is 57332:

    <SECTION2 LBL="" HELPID = ""><TITLE>Supplementary Reading<XREFTARGET ID="57332"></TITLE><PARAGRAPH>Refer to these documents to supplement the information in this guide:</PARAGRAPH>

  5. Click the New Marker button to create a new marker containing the information you've specified.

  6. Move the cursor from the beginning of the text where the cross-book link will be placed to the end of the text.

  7. From the Marker dialog box, select Type 19 from Marker Type. Leave the Marker Text box empty.

  8. Click the New Marker button to create a new empty marker of type 19.

The result is a piece of your document with this structure:


text is the text that will be marked as a link, the type-18 marker contains the name of the target book and the ID of the target element, and the type-19 marker is empty (a placeholder to indicate the end of the cross-reference text).

Note: Unless the text between the markers is a document title, the text between the two markers cannot contain character tags. In the case of a document title, tag the document title and both markers with the DocTitle character tag.

Using the Cross-Reference Utility to Create an External Book Link

The following procedure explains how to create a link to another book using the FrameMaker cross-reference utility. Note that in order to create a cross-book link using this method, you need to have access to the FrameMaker document files that were used to create the book to which you are linking. You also need to know the target book's short title. The short title can be obtained from the target book's Makefile.

This procedure is a bit tricky because you have to specify both the target filename and the short title of the target book. To make a cross-book link, follow these steps:

  1. Obtain a copy of the target book's document files and Makefile. Place the copy in a directory named short title (the short title of the target book), or else create a symbolic link named short_title that links to the directory containing the copy of the target book. The directory or symbolic link can be anywhere in your filesystem, as long as it's called short_title.

  2. Open up the target file in FrameMaker. When opening it, be certain to navigate to the file by way of the directory or symbolic link named short_title; if you don't do this, your link won't work.

  3. Open your file that will contain the cross-book cross reference and place the cursor where you want the cross reference to go.

  4. From the Special menu in your document window, choose “Cross-Reference... “

  5. From the Source Document menu in the resulting dialog, select the name of the file that contains the section you want to reference.

  6. Choose the Source Type called Cross Reference Markers.

  7. Select the appropriate Reference Source.

    Note: The Cross Reference Markers list is a list of FrameMaker cross-reference targets in the target file. If the target you want to reference does not appear in the list of Cross Reference Markers, then it does not have an associated cross-reference target and you cannot reference it.

  8. Select a cross-reference format.

  9. Click the Insert button.

  10. Remove the target document from your system using your usual procedures.

Note: Be sure to use separate directories for different language versions of the same book. The same TITLE is used for the same book in all languages. For example, PerSysAdmin is used for the German, French and English versions of the same book. IRIS InSight checks the lang environment variable and uses the TITLE (PerSysAdmin) from the appropriate lang directory. If lang is set to DE, the German PerSysAdmin is used.

Determining If a Book Has External Book References

After building the book, use more or jot to view the *.full file. Example 4-1 shows the portion of the file specific to links.

Example 4-1. *.full File Quality Assurance Report for Links

=== Desktop_UG Link QA report file ===
 Link targets appearing multiple times in book:
 Unresolved References present in this book: none
 External Book References present in this book: 
   PerSysAdmin appears 16 time(s)

PerSysAdmin is externally cross-referenced 16 times in this manual.

Testing External Cross-References

To test external cross-references, all the affected books must be installed. For the book in Example 4-1, the Desktop User's Guide and Personal System Administration Guide must be installed before testing can be done. To install books, use the installtestbooks script as described in “Installing a Localized Book for Testing”. Then launch IRIS InSight, choose the appropriate bookshelf, and open the book by clicking the book's icon. An IRIS InSight viewer appears and shows the first chapter or introductory section of the book along with its Table of Contents.

Finding Cross References in IRIS InSight

To find the cross references in IRIS InSight:

  1. Enter the following line of text in the Find box:


  2. Click the Search button.

All the external cross references in the IRIS InSight book are highlighted. If you look at the top of the Table of Contents for the IRIS InSight book, you see a number that indicates how many times an external cross reference occurs.

To test the external cross references, scroll through the book to the locations indicated by the search results and look for bold red text. All red text indicates external cross references or launchable reference pages.

Testing the Link

Click the external cross reference (red text). Another IRIS InSight viewer opens and displays the linked book. The linked book shows either its first chapter or introductory section or a specific heading for which the link was established. Continue checking all external cross references.

If the cross-referenced book is not installed, or if the link was incorrectly created, a dialog box, such as shown in Figure 4-1, appears.

Figure 4-1. Example of a Link That Cannot Be Followed

Notice the title of the book that cannot be followed is SiteAdmin. This is the short title of the book. A typical short title is a series of initials or an abbreviation sometimes separated by an underscore. If you see a book's part number in the IRIS InSight Warning dialog box, the link did not work because part numbers cannot be used in place of the short title. If the short title format appears correct but doesn't work, check to be sure the short title is spelled correctly.

Multiple Cross Reference Targets

The section explains the following:

Cross-Reference Targets

Hypertext books incorporate cross references and cross-reference targets. A cross reference is an item you click in order to jump to another location. The target is the location where you end up after clicking on a cross reference.

While reading an online document, the reader sees most of the text in black but occasionally some text in blue. This blue text is the cross reference. In the example shown in Figure 4-2, the cross reference is referring to Figure A, and Figure A is located two paragraphs below the cross reference. When the reader clicks on the blue “Figure A” text, they are automatically jumped to the image and title for Figure A.

Figure 4-2. Diagram of Cross Reference Targets

How Multiple Cross References Target Occur

Multiple cross references targets usually occur when a writer copies a chunk of text, including the target markers, from one document file and then pastes it into another document file.

Once a figure title (tagged as FigTitle) is created in FrameMaker, a cross reference can be made to FigTitle. Figure 4-3 shows an example of a figure title that has no cross reference linking to it.

Figure 4-3. Figure without a Cross Reference Target Marker

Figure 4-4 shows a figure title after a cross reference target marker was made. Notice the bold T symbol after the text “Figure A.” The T symbol is the marker that is automatically generated when a cross reference is created.

Figure 4-4. Figure with a Cross Reference Target Marker

Once an anchored frame and its figure title and the cross reference are created, a writer might copy the figure and figure title (and the cross reference marker) and then paste it somewhere else in the document. If you were to look at the text for the marker in Figure 4-4, it would look like this:

24340: FigTitle: Figure\ 1-3 A Figure with a Cross Reference Target Marker

You can see this for yourself in a Frame document by selecting the marker and choosing Marker ... from the Special menu. The number 24340 is the unique identifier that is used by the online build tools to create Targets. If the marker is copied, the unique identifier is copied with it. So if the figure title for Figure 4-4 were copied and used for Figure 1-4, the marker for Figure 1-4 would look like:

24340: FigTitle: Figure\ 1-4 A Different Figure 

Notice that the number at the beginning of the string is exactly the same. This poses a problem for the tools, which look primarily at this number and not the title. The tools ignore the figure number and title that show up in the marker box. The tools create a figure number and title from other information supplied, such as autonumbering.

Note: Multiple cross-reference targets are no longer a problem in some versions of FrameMaker.

How to Fix Multiple Cross Reference Targets

This section explains how to identify and fix multiple cross reference targets.

Identifying Multiple Cross References

In the *.full file for the 3.4 and subsequent build tools, there is a section that identifies multiple cross reference targets. The first step in fixing the problem is to identify the targets.

In the *.full file you may get output that looks like the following:

Link targets appearing multiple times in book:
 48482 :  Bouton de la barre d'outils permettant d'afficher et de cacher l'&eacute;tag&egrave;re.
 48482 :   Bouton de la barre d'outils permettant d'afficher les fichiers images.
 60723 :  Utiliser la barre du chemin d'acc&egrave;s.
 60723 :   Utilisation de la barre du chemin.
 93693 :  Commande &ldquo;Chercher ic&ocirc;ne&rdquo; 
 93693 :   Commande &ldquo;Chercher ic&ocirc;ne&rdquo; 

The five-digit number at the beginning of each string is in the list at least twice. The error report lists only the unique identifier and the title, and nothing else.

To locate which FrameMaker document has these multiple target markers, use the grep command as follows:

  1. Use grep to determine which document(s) contain the target markers.

    grep 60723 *.sgm

    This should produce something that looks like the following:

    ch10.sgm:<SECTION3 LBL=”” HELPID = “fmcon_pathbar”><TITLE>Barre du chemin</TITLE><PARAGRAPH>La barre du chemin est la petite barre grise affich&eacute;e au-dessus du champ du chemin. Elle vous permet de passer directement d'un r&eacute;pertoire &agrave; un autre gr&acirc;ce &agrave; un petit bouton affect&eacute; &agrave; chaque r&eacute;pertoire du <GLOSSARYITEM>chemin</GLOSSARYITEM>. Cliquez sur l'un d'eux pour afficher le contenu d'un r&eacute;pertoire (voir <XREF IDREF=”60723” TYPE=”GRAPHIC”>Figure&nbsp;10-3</XREF>).</PARAGRAPH>
    ch10.sgm:<PARAGRAPH><FIGURE><GRAPHIC FILE=”pathbar.gif” POSITION=”INLINE” SCALE=”FALSE”><CAPTION LBL=”11-3”><PREFIX>Figure 10-3 </PREFIX><XREFTARGET ID=”60723”>Utilisation de la barre du chemin.</CAPTION>
    ch4.sgm:<SECTION3 LBL=”” HELPID = ““><TITLE>Utiliser la barre du chemin d'acc&egrave;s dans l'outil de recherche d'ic&ocirc;ne</TITLE><PARAGRAPH>La barre du chemin d'acc&egrave;s est la barre grise situ&eacute;e au-dessus du champ de saisie rose. Elle vous permet de vous d&eacute;placer d'un r&eacute;pertoire &agrave; l'autre, sans entrer son nom complet. Elle contient un petit bouton repr&eacute;sentant chaque r&eacute;pertoire dans le <GLOSSARYITEM>nom du chemin</GLOSSARYITEM>. Cliquez sur un bouton pour afficher le contenu de ce r&eacute;pertoire (voir la <XREF IDREF=”60723” TYPE=”GRAPHIC”>Figure&nbsp;4-4</XREF>).</PARAGRAPH>
    ch4.sgm:<PARAGRAPH><FIGURE><GRAPHIC FILE=”pathbar.gif” POSITION=”INLINE” SCALE=”FALSE”><CAPTION LBL=”4-4”><PREFIX>Figure 4-4 </PREFIX><XREFTARGET ID=”60723”>Utiliser la barre du chemin d'acc&egrave;s.</CAPTION>

    Notice there are four locations where this ID number occurs. The number shows up twice in ch4.sgm and twice in ch10.sgm. The XREF IDEF is the cross reference and the XREFTARGET is the cross reference target. Because there are two targets using the same cross reference ID, this configuration will not work.

  2. Either remove the target in ch4.sgm or the target in ch10.sgm and establish a new cross reference to the target.

    Remove the target that has the fewest cross references pointing to it.

When a cross reference is clicked in the online version of the book, it starts searching the document from the beginning for the matching target and stops at the first one it reaches. For the information listed above, clicking the cross reference for Figure 10-3 jumps to Figure 4-4 because it occurs first in the document.

Cross Reference Target Scenarios

Scenario 1: A document has two targets and one cross reference.
If the cross reference refers to the first target, then the document will work.
If time permits, you should delete the target that is not being used.

Scenario 2: A document has two targets and one cross reference.
If the cross reference refers to the second target, then the document will not work.
You must delete the target that is not being used.

Scenario 3: The document has two targets and several cross references pointing to one target and only one cross reference pointing to the other target.
You should delete the target that has only one cross reference pointing to it.