Chapter 6. Finding and Fixing Online Build Errors
Prev |  | Next

## Chapter 6. Finding and Fixing Online Build Errors

This chapter describes the errors and warnings that can occur when FrameMaker files are converted to SGML format using the `mif2sgidocbk` translator.[2] It compares the FrameMaker and SGML versions of a sample file and identifies the intermediate files that are created to store errors in the translation process. It also lists some common error messages and explains how to correct them.

This chapter contains these sections:

- “About Error Messages” discusses error messages and the basic process for finding and resolving them.

- “Error Files” lists and describes the various files generated by the online tools during the conversion to SGML.

- “About SGML ” discusses SGML and provides a simple example of an SGML file.

- “Checking the .full File” tells you how to look at the .err files and `.full` file for error messages generated during conversion.

- “Finding and Fixing Errors” explains how to find error messages and warnings in the .sgm files, how to pinpoint the location of errors in the FrameMaker files, and how to interpret error messages. This section also lists some common .sgm file error messages and their causes.

- “Checking for Display Problems” explains how to review the document for dangling cross-references, dangling glossary items, and typical display problems.

## About Error Messages

While your book is in development, even if your `make` command completes successfully (that is, doesn't terminate prematurely with a `make` or `smake` error), chances are that the content of your book still contains errors. These errors usually involve tags and structures that the translator considers invalid. The conversion tools report such problems as error messages in the SGML output. Before you check in the final version of your book, you must examine the error messages, fix the problems that caused them, and build a clean version of your book with the `make book.full` command. (A “clean” book is one which generates no ERROR messages or link problems during conversion.)

## Error Files

Depending on the specific `make` command you run, you can generate a number of different error files. (See “Using make Commands” in Chapter 5 for more information on `make` commands.) The `.full` and `.err` files in this list are the most useful files for error tracking:

.`err` file |  | An `.err` file contains errors and warnings generated from the corresponding SGML file, as well as information on obsolete or unrecognized tags from the corresponding `.mif` file. You should fix all messages labeled `ERROR`, but you may ignore the messages labeled `WARNING`.
short_title`.full` file |  | The `make book.full` command generates a file called short_title`.full` that contains a complete error report for the entire book. This is the only error report that contains information on links and unresolved glossary terms.

## About SGML

Each .sgm file contains the SGML version of its associated FrameMaker file. In SGML, each item is assigned a structural tag, similar to a FrameMaker tag, that describes that item's role in the overall document. So, in SGML, as in FrameMaker, an item (such as a paragraph or a phrase) might be tagged as part of a hanging list, or as a command, or as a chapter title. A word or phrase can have multiple (nested) labels, as happens with a command within a hanging list.

When the conversion tools find something in the FrameMaker file that they don't know how to tag, or when they find an item located where it's not supposed to be (such as a HangingList paragraph tag before the ChapTitle tag), they produce an error message. The example .`sgm` file in “Example SGML File” shows what error messages look like within an SGML file.

If you're internal to SGI, refer to the Guide to the SGIDOCBK DTD, 007-0119-001, for more information about SGML.

### Example SGML File

This section contains an example FrameMaker document file and the corresponding example .`sgm` file generated by the `make book.full` command.

#### The FrameMaker File

Figure 6-1 shows an example FrameMaker file. This one-page document contains several paragraph and character tags, including an invalid structure that would generate an error message during online translation. The invalid structure is a set of square-bulleted paragraphs within a set of round-bulleted paragraphs; the BulletSquareInd tag should only be used for sub-steps within a step in a numbered list. ( See Appendix A, “Using the SGI Book Building Templates to Author Documents”, for more information on which structures are legal and which aren't in a document.)

Figure 6-1. FrameMaker Example File

#### The SGML File

The listing in Example 6-1 represents the .`sgml` file for the FrameMaker file shown in Figure 6-1. Look for names of character and paragraph tags to get an idea of how SGML tags work (“SGML Tag Structure” explains the structure of SGML tags in more detail). Notice the `ERROR` lines in the middle of the file. This is how error messages appear within SGML files. The build tools copy all the error messages from each `.sgm` file into a corresponding `.err` file as well as into the .`full` file for your convenience.

Example 6-1. SGML Translation of Example FrameMaker File

    <!-- Produced by version 4.001 (9/98) of SGI Frame/SGIDOCBK SGML translator -->
    <CHAPTER><TITLE>About the Mottled Oyster</TITLE><PARA>The mottled oyster is an exciting and superfluous new application that allows you to issue
    <!-- ERROR: (4) Unknown Frame tag "Slang" encountered - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "CHAR" TAG = "Slang" TAGCOUNT = "1" UID = "324065" TEXT = "corking"-->
    <DUMMY tag="Slang">corking</DUMMY>
     commands such as <LITERAL>G&amp;T</LITERAL> (Gin &amp; Tonic; see the G&amp;T(1) reference page for details). If you read this tutorial carefully, you're sure to have a <GLOSSTERM>jolly good time</GLOSSTERM> with the mottled oyster. After a few hours with this tutorial you will be able to use the <LITERAL>oyster</LITERAL> command to do your work more quickly and efficiently. You will learn</PARA><ITEMIZEDLIST><LISTITEM><PARA>how to prepare your files for bunging into <LITERAL>oyster</LITERAL></PARA>
    </LISTITEM>
    <LISTITEM><PARA>general rules to avoid aunts and other threats</PARA>
    </LISTITEM>
    <LISTITEM><PARA>the correct intonation for phrases like</PARA>

    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "1" UID = "324242" TEXT = "&ldquo;tally ho!&rdquo;"-->
    <ITEMIZEDLIST><LISTITEM><PARA>&ldquo;tally ho!&rdquo;</PARA>

    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "2" UID = "324246" TEXT = "&ldquo;hey what?&rdquo;"-->
    </LISTITEM>
    <LISTITEM><PARA>&ldquo;hey what?&rdquo;</PARA>

    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "3" UID = "324243" TEXT = "&ldquo;old bean&rdquo;"-->
    </LISTITEM>
    <LISTITEM><PARA>&ldquo;old bean&rdquo;</PARA>
    </LISTITEM>
    </ITEMIZEDLIST>
    </LISTITEM>
    <LISTITEM><PARA>how to request information from a butler</PARA>
    </LISTITEM>
    </ITEMIZEDLIST>
    <PARA>To use this tutorial you need a basic understanding of these items:</PARA><DEFLIST><DEFLISTENTRY><TERM>cow creamer</TERM>
    <LISTITEM><PARA>A cow-shaped container holding cream for use in tea. You should be familiar specifically with the use of the eighteenth-century English cow creamer.</PARA>
    <PARA>Of course, you must beware of Modern Dutch cow creamers posing as eighteenth-century English cow creamers.</PARA>
    </LISTITEM>
    </DEFLISTENTRY>
    <DEFLISTENTRY><TERM><LITERAL>vi</LITERAL> text editor</TERM>
    <LISTITEM><PARA>Allows you to edit text using arcane and cryptic commands.</PARA>
    </LISTITEM>
    </DEFLISTENTRY>
    </DEFLIST>
    <PARA>You might want to look at a copy of the <CITETITLE>Code of the Woosters</CITETITLE> when you're finished with this tutorial.</PARA>
    </CHAPTER>

The usual method of finding such errors is to look at the `.err` output files after issuing a `make` command. However, you may sometimes need more information about where exactly in a chapter the error occurs. The simplest approach to finding an error in context is to use a text editor (such as `emacs`, `vi`, or `jot`) or a pager (such as `more` or `less`) to locate all occurrences within a file of the word “ERROR”.

### SGML Tag Structure

You can see from the example in “The SGML File” that SGML tags come in pairs. Each tag pair contains an opening tag and a closing tag, and the opening tag applies to all of the content between it and the closing tag. Figure 6-2 shows an example of SGML opening and closing tags with tagged content, in this case simply the word “oyster.”

Figure 6-2. SGML Opening and Closing Tags

## Checking the `.full` File

The `short_title.full` file provides a complete list of all the errors, warnings, and link problems in your book. This list consists of four separate kinds of reports:

- the translation error and warning report (one for each FrameMaker file)

- the internal SGI doc report listing the defined parameters from the Makefile

- the link QA report file (a single report for the entire book)

- the glossary QA report file (a single report for the entire book)

Each report starts with three equals signs (“===”) to set it off from the previous report.

You must fix all the errors listed in the error and warning report and the link QA report. You should fix the errors listed in the Glossary QA report, but if you don't fix them your, book will still build.

This section begins with an example `.full` file, then goes on to explain how to deal with each of the three types of report files contained in a `.full` file.

### An Example `.full` File

This section contains the .`full` file corresponding to the example FrameMaker file shown in Figure 6-1 (for the purposes of this example, assume that the single page of FrameMaker text is an entire book).

    === oyster.err Translation Error/Warning report ===
    <!-- ERROR: (4) Unknown Frame tag "Slang" encountered - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "CHAR" TAG = "Slang" TAGCOUNT = "1" UID = "324065" TEXT = "corking"-->
    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "1" UID = "324242" TEXT = "&ldquo;tally ho!&rdquo;"-->
    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "2" UID = "324246" TEXT = "&ldquo;hey what?&rdquo;"-->
    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "3" UID = "324243" TEXT = "&ldquo;old bean&rdquo;"-->

    === Mottled_Oyster Link QA report file ===

     Link targets appearing multiple times in book: none

     Unresolved References present in this book: none

     External Book References present in this book: none

### The Translation Error and Warning Report

The translation error and warning report contained in the `.full` file provides a complete list of all the translation errors and warnings in your book, grouped by chapter. Before you hand off your final book to be incorporated into a software build, you must fix all the translation errors so that no error messages appear in the translation error and warning report. You do not need to fix warnings (marked as `WARNING` instead of `ERROR`); you can ignore them, but you might want to look at pages where warnings occurred when you review the book in a web browser to catch any display problems).

Here's the translation error and warning report for the example FrameMaker file shown in Figure 6-1.

    === oyster.err Translation Error/Warning report ===
    <!-- ERROR: (4) Unknown Frame tag "Slang" encountered - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "CHAR" TAG = "Slang" TAGCOUNT = "1" UID = "324065" TEXT = "corking"-->
    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "1" UID = "324242" TEXT = "&ldquo;tally ho!&rdquo;"-->
    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "2" UID = "324246" TEXT = "&ldquo;hey what?&rdquo;"-->
    <!-- ERROR: (77) BulletSquare tags should only be nested within an ordered list - detected on page 1 -->
    <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "3" UID = "324243" TEXT = "&ldquo;old bean&rdquo;"-->

The report includes, for each error, the error message itself (the part that starts with “`<!-- ERROR:`”) and the chunk of SGML that contains the error (the part that starts with “`TEXT =`”). The error message briefly describes the problem and gives a page number for the page in the FrameMaker file where the error occurred. You can see which file the error is in because you get a separate error report for each FrameMaker file.

In this example, the problem is that the writer has tried to use the BulletSquareInd paragraph tag to create a bulleted list within a bulleted list. This is an illegal structure. To fix this problem, the writer must open the FrameMaker file and re-tag the offending paragraphs with the DashInd paragraph tag. Square bullets should only be used to mark sub-steps within a numbered list; DashInd should be used for sub-bullets within a round-bulleted list. See Appendix A, “Using the SGI Book Building Templates to Author Documents”, for more information on which structures are legal and which aren't within a document.

### The Link QA Report

The link QA report is the third report contained in the `.full` file. It lists multiple link targets, unresolved cross references, and all externally cross-referenced books (it just lists the short title and a 5-digit MIF marker ID for each book; it doesn't verify the links.) Here's the link QA report for the FrameMaker file shown in Figure 6-1:

    === Mottled_Oyster Link QA report file ===

    Link targets appearing multiple times in book: none

    Unresolved References present in this book: None

     External Book References present in this book: None

In this example, there were no multiple link targets, unresolved cross-references, or externally cross-referenced books.

#### Multiple Link Targets

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. The example described here occurs when copying figures from one location in a book to another.

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

Figure 6-3. Figure Without a Cross Reference Target Marker

Figure 6-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 6-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 6-4, it would look like this:

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

You can see this for yourself in a Frame document by selecting the marker and choosing Special > Marker. 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 6-4 was copied and used for Figure B, the marker for Figure B would look the same:

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

Notice that the number at the beginning of the string is exactly the same. This poses a problem for the tools, which look 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: FrameMaker 5 and FrameMaker 5.5.6 do not allow the pasting of a duplicate MIF marker within the same document. If content is copied with the MIF marker and then pasted elsewhere in the same file, the content will be pasted, but the marker will not be.

#### Finding and Fixing Multiple Link Targets

In the *.`full` file for the 4.2 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:
     ----------------------------------------------
    'LE97649-PARENT' :
    'LE97649-PARENT' :
    'LE97649-TITLE' : LE97649-PARENT How to Use This Tutorial
    'LE97649-TITLE' :  LE97649-PARENT How to Use This Tutorial

Notice that the five-digit number after the “LE” 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, perform the following steps:

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

       grep 97649 *.sgm

   This should produce something that looks like the following:

       oyster.sgm:<PARA>See <XREF LINKEND="LE97649-TITLE"> for more information.</PARA><SECTION  ID="LE97649-PARENT"><TITLE  ID="LE97649-TITLE">How to Use This Tutorial</TITLE><PARA>To use this tutorial you need a basic understanding of these items:</PARA>
       oyster2.sgm:<PARA>See <XREF LINKEND="LE97649-TITLE"> for more information.</PARA><SECTION  ID="LE97649-PARENT"><TITLE  ID="LE97649-TITLE">How to Set Up an Oyster Farm</TITLE><PARA>First, you'll need to acquire a stretch of beach near some prime mottled oyster beds.</PARA>

   Notice there are four locations where this ID number occurs. The number shows up twice in `oyster.sgm` and twice in `oyster2.sgm`. The `XREF LINKEND` is the cross reference and the `SECTION ID` or `TITLE ID` 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 `oyster.sgm` or the target in `oyster2.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 LE97649 jumps to the section “How to Use This Tutorial” because it occurs first in the document.

Table 6-1. Cross Reference Target Scenarios

Scenario | Situation | Solution
--- | --- | ---
A document has two targets and one cross reference | If the cross reference refers to the first target, then the document will work | Delete the target that is not being used
A document has two targets and one cross reference | If the cross reference refers to the second target, then the document will not work | Delete the target that is not being used
The document has two targets and several cross references pointing to one target and only one cross reference pointing to the other target | Varies with the position of the targets within the book. | Delete the target that has only one cross reference pointing to it

#### Unresolved References

Some unresolved cross references that FrameMaker doesn't notice are trapped by the build tools. Usually such undetected cross references are caused by remnants of incomplete conversions to a new template or from third-party documentation. You can check for remnant cross references using the Edit > Find/Change tool to search for “Any Cross-Reference.” The link QA report error indicates the approximate location of unresolved references. If you have problems finding the unresolved reference, try using `grep` to find the MIF or .`sgm` files containing the referenced FrameMaker marker ID, then look in those files after the given marker ID. Sometimes there's an extraneous FrameMaker marker containing a cross reference or cross-reference target, and sometimes the link QA report identifies a nearby marker rather than the marker with the problem.

The QA report lists the short titles and corresponding 5-digit unique IDs for each external book link included in your document. Review the short titles to ensure they are correct for the books you want to link to from your book.

## Finding and Fixing Errors

This section discusses error messages that you may encounter while building a book, and explains how to find and fix the corresponding errors in your FrameMaker files.

### Types of Errors

There are three general categories of errors that can occur during the bookbuild process:

- `make book` errors (see “make book Error Messages” in Chapter 5 for details)

- MIF-to-SGML translation errors (see the following sections for details)

  - “Critical Input or Internal Problems (1-99)”

  - “Structural Problems (100-199)”

  - “Marker and Related Problems (200-299)”

- XML and xsltproc errors

- unknown errors (see “Unknown Errors”)

Error messages for `make book` errors appear in the shell window in which you enter the `make` command. Error messages for MIF-to-SGML translation errors and unknown errors appear in files generated during the build process.

Errors are listed in several different files. As explained in “Checking the .full File”, all the errors from all the files are listed in the `short_title.full` file, so that file is a good place to start looking for errors. However, once you have a general idea of what errors (and how many) are present in your book, you may prefer to work from a file with smaller scope, such as the `.err` file for a particular chapter, and to look in individual `.sgm` files to find the context a given error occurred in. “Error Files” describes the different files generated by the conversion tools, and “Using make Commands” in Chapter 5 explains how to use the `make` command to generate a specific type of file.

### Finding the Errors in FrameMaker Files

To find a given error, open the FrameMaker file that contains the error, go to the listed page number, and look for the problem. “MIF-to-SGML Translation Errors” lists some common numbered error messages and their causes, so look for your error message in that list.

Often the problem is easy to spot: an empty anchored frame or a mis-formatted table, for example. Sometimes, however, the problem is more difficult to find. “Unknown Errors” lists some tips to help you find more obscure errors.

### MIF-to-SGML Translation Errors

If the translator thinks it knows what the problem is, it provides an error message that looks something like this:

    ch1.sgm: <!-- ERROR: INFORMATIVE, HELPFUL ERROR MESSAGE HERE -->

or

    ch4.sgm: <!-- WARNING: STOP YOUR SLACKIN' -->

This type of error is called a known error, because it comes with an informative error message. This section contains a sample of known error messages with explanations and suggestions for fixes. The messages are listed in numerical order, according to the number in parentheses at the beginning of each message. If your error message isn't listed here, follow the instructions in “Unknown Errors”.

Note that error messages and warning messages generated during MIF-to-SGML translation have the same basic structure; however, error messages usually indicate that the book won't build properly, while you can safely ignore warning messages if you prefer.

#### Critical Input or Internal Problems (1-99)

1

Unknown Frame tag [tag_name] encountered

There is an unrecognized paragraph or character tag used in a table or in your document that is not supported by the translator.

Solution: Don't use the tag.

- Search for the unrecognized tag in the document file and replace it with a recognized one.

- If the tag is not found, see if the table uses an unrecognized table format and replace it with a recognized format.

2

Maximum number of table footnotes exceeded

A table can only have 26 footnotes.

Solution: Use fewer footnotes or split the information into multiple tables.

3

“Character tag [tag_name] spans Hanging List delimiter”

Character tags shouldn't be applied to whitespace (such as tabs and hard and soft returns). This error message indicates that you've applied a character tag to both parts of a hanging list, including the tab that separates them.

Solution: Apply Default Paragraph Font to the whitespace between the two parts of the hanging list. Tag each part separately.

4

“Illegal structure starting at `[tag_name]'”

A major structural error occurred.

Solution: Review the location where the error occurred for potential problems.

5

“XREFNAME has a value [value]”

An internal warning that information saved about a cross reference was not used. After the translator is completed, this message may be disabled.

Solution: If no cross reference errors exist in the .`full` file, ignore this message.

6

“An ID Value [value] was not used”

An internal warning that should never occur. If it occurs, it is very likely that a cross reference error will exist in the .`full` file.

Solution: Contact techpubs@sgi.com for assistance.

7

“Use of override is not allowed”

The <override> tag is not used in the SGIDOCBK DTD and cannot be supported.

Solution: Reformatted the affected part of the document to avoid using the override marker.

8

“Illegal tag in variable: [value]”

A supported tag name could not be found in the listed value. This should be a very rare error.

Solution: Examine the document for potential problems. You can use character tags in variables, but you can't use any character tags that you couldn't use in ordinary text.

10

“Tag [tag_name] is obsolete or print-only”

The specified tag is no longer supported or else should be tagged as PrintOnly to avoid translation for online display. Use of the tag may work, but should be replaced with an appropriate supported tag when possible.

Solution: Don't use the tag for online content. Find and replace all occurrences of such tags using FrameMaker's Edit > Find/Change tool.

11

“BNFTerm and BNFRule are obsolete and shouldn't be used”

The BNFTerm and BNFRule tags are no longer included in the IPTemplates used by SGI; however, the SGIDOCBK DTD can still translate them.

Solution: Either eplace the obsolete tags with a different paragraph tag such as HangingList or use a TabularList to format the information, or ignore this message.

20

“INTERNAL: No error message for AV_error”

The AV_error() function was called when the AV_msg string variable was not set.

Solution: This is a programming bug and shouldn't occur for end users.

21

“Untranslated Function Character ([char])”

The translator was unable to convert a special character value into a character entity.

Solution: Search the FrameMaker document for the special character—it may be easiest to find its location by first using `grep` to search for `character_name` in the MIF file—and replace it with a standard character. If the character must be used, contact the SGI tools people to update the translator or don't use the character.

22

“INTERNAL: Unclosed Tags [one or more tags]”

This indicates a serious parsing problem occurred and is usually caused by an item being tagged that should not be tagged or by an uncompleted sequence of more than one tag. For example, your file might contain a hanging list that includes a list item without a body.

Solution: Check the tagging and ensure all the components of a structure are present. If the MIF file is valid, then the bug must be fixed in the program.

23

“Cannot process Frame on page X [tag_value]”

An anchored frame cannot be processed because it was set up incorrectly or because it is empty.

Solution: Verify that the anchored frame is question is set up correctly and import a figure into the anchored frame. See Chapter 4, “Working With Figures”, for instructions. If a figure isn't ready, you can ignore this error message, view your book without the figure, and import the figure when it becomes available.

24

“Cannot process Indirect Frame [tag_value] on page X”

A problem occurred while processing the specified frame, usually a margin figure.

Solution: Double check that the frame is used correctly. Margin figures are no longer supported by the translator, so attach the anchored frame to a Fig tag and set it up as you would an inline figure. See Chapter 4, “Working With Figures”, for instructions.

25

“INTERNAL: MIF Stack Overflow!”

There is a predefined limit to the nesting of MIF tags. In normal usage that limit should never be exceeded.

Solution: The MIF file cannot be correctly processed.

26

“INTERNAL: MIFPopPgfTag on empty stack!”

The input MIF file is syntactically incorrect.

Solution: Use FrameMaker to verify if the MIF file is valid or recreate a new one from the original .`doc` file.

27

“INTERNAL: Unrecognized MIF Command Name”

An unknown MIF tag type occurred. This is different than an unknown paragraph type occurring.

Solution: Check that the MIF file is valid.

28

“INTERNAL: MIFPushPgfTag stack is full!”

The predefined limit for the nesting of paragraph types was exceeded. This should never occur in normal usage.

Solution: Verify that the MIF file is valid or contact techpubs@sgi.com for assistance.

29

“INTERNAL: Negative Nesting Level”

This error should never occur with a valid MIF file.

Solution: Check that the MIF file is valid or contact techpubs@sgi.com for assistance.

30

“INTERNAL: Unmarked data encountered”

The translator found MIF data that it could not process. The data is ignored unless other actions are taken.

Solution: The MIF file cannot be correctly processed.

31

“Structural loop in setting element [element] [more information]”

The SGML structure programmed into the translator is flawed and causing an endless loop of elements.

Solution: The MIF file cannot be correctly processed.

32

“Illegal element [element] [more information]”

The SGML structure programmed into the translator is flawed.

Solution: The MIF file cannot be correctly processed.

33

“Unknown Generic Identifier: [element]”

The translator code specified an unknown SGML element.

Solution: The MIF file cannot be correctly processed.

#### Structural Problems (100-199)

100

“GlossDiv, must occur before any glossary entries”

The GlossDiv structure is designed to be a container of multiple GlossEntry structures. If GlossDiv is used, it must be used before any glossary entries in order to correctly contain them.

Solution: Move the first GlossDiv paragraph before the first glossary entry or remove all GlossDiv paragraphs.

101

“Glossary tag usage in this context probably incorrect”

The use of a GlossaryDef tag or a GlossaryEntry tag has occurred outside of a glossary.

Solution: Move any GlossaryEntry paragraphs into the glossary document or retag the affected paragraphs with more appropriate paragraph tags.

110

“Poorly formatted partnumber paragraph. Check for a correct partnumber xxx-xxxx-xxx”

The translator was unable to find all three parts of the part number in the DocNumber paragraph (in the `front.doc`).

Solution: Make sure the paragraph has a correct part number in the form of xxx-xxxx-xxx.

111

“Structure problem in revision”

The revision paragraph is formatted such that it is impossible to determine what content is the rev number and date (in the `RecRev.doc`).

Solution: Verify that the revision paragraph is formatted correctly.

112

“The Heading[2,3,4,5] tag occurred without the proper parent headings.”

Heading paragraphs must be nested in the proper order. For example, this error could be caused by a Heading3 occurring after a Heading1 without a Heading2 in between.

Solution: Correct the ordering of the HeadingX paragraphs.

113

“Example or Code captions should come at the beginning of the block”

The title for an Example or Code block must come before the example or code block of text.

Solution: Move the title so it is placed directly before the respective block of example or code text.

114

“MsgExpl used without preceding Msg tag”

The Msg paragraph tag is part of a construct for displaying error messages that consists of one or more Msg* paragraph tags followed by one or more MsgExpl paragraph tags. This error indicates that the MsgExpl tag was used without a preceding Msg tag. The MsgExpl paragraph can only be used when it follows either a Msg[1st] or MsgMargin[1st] paragraph.

Solution: Make sure the Msg* paragraphs are tagged and ordered correctly.

115

“Empty figure PARA!”

A figure is located in a paragraph not tagged as Fig.

Solution: Tag the paragraph containing the figure as Fig.

116

“Unable to determine figure filename”

The translator couldn't find the information about the figure's filename.

Solution: Verify that the figure is imported-by-reference from the `print` dir and that the Fig paragraph is tagged correctly.

120

“TableTitle should only occur in a table”

A paragraph tagged as TableTitle has been found outside of a table construct. The TableTitle paragraph can only occur directly before a table.

Solution: Make sure the TableTitle paragraph is located right before the table it labels.

121

“Table figure not located in a table”

A table figure has occurred outside of a table.

Solution: Make sure the figure in question is located and tagged correctly.

122

“An empty table footnote occurred. Check to make sure it is tagged as TableFootnote”

A footnote inserted in a table must be tagged with the TableFootnote tag rather than the Footnote tag.

Solution: Tag the paragraph as TableFootnote.

130

“This list should only be nested within another list”

A nested list paragraph, such as any of the *Ind list paragraphs, must reside within another list.

Solution: Make sure the list paragraphs are ordered correctly.

131

“BulletSquareInd paragraph should only be nested after a List[1st] paragraph”

The BulletSquareInd paragraph tag is only valid when nested in numbered lists. This requirement ensures the formatted SGML will look similar to the FrameMaker document.

Solution: Make sure a List[1st] paragraph occurs directly before the BulletSquareInd paragraph.

132

“This list is nested incorrectly. Should be at the third level of indentation.”

The list paragraph tags should be nested in the correct order. For example, a ListInd4.1st shouldn't occur directly after a List1st because it skips the level made up by the *Ind paragraphs.

Solution: Make sure the order of the list paragraphs is correct or reorder the list.

133

“The Frame tag ListInd4[.1st] or BulletInd4 (or ProcTitleInd4) should not occur in this context”

The ListInd4, BulletInd4, and ProcTitleInd4 paragraphs can not be used within a MsgExpl or HangingList.

Solution: Move the affected paragraphs or tag them as an acceptable paragraph type.

134

“The Frame tag ProcTitleInd should only occur nested within a list”

A list paragraph must be used before the indented ProcTitleInd paragraph in order for the tag to be valid.

Solution: Verify that a List paragraph occurs before the ProcTitleInd paragraph or use the ProcTitle paragraph instead.

135

“ProcSubTitle should only occur nested within a procedure”

A procedure must be started using the ProcTitle paragraph before ProcSubTitle can be used.

Solution: Ensure this is really a nested procedure that was started with a previous ProcTitle paragraph or change this paragraph to use ProcTitle.

136

“HanglistInd not legal in this context”

The HangingListInd tag cannot structurally reside in this position in the FrameMaker file. For example, you can't legally put a HangingListInd tag inside a BulletInd list.

Solution: Restructure your list so the tag use is legal.

140

“Hierarchy problem for [tag_name]”

The translator was unable to create an open tag for the paragraph contents or was unable to create an SGML <PARAGRAPH> tag for a figure definition. This means the paragraph tag or figure definition (using the Fig paragraph tag) has been applied somewhere it's not supposed to be, such as before a ChapTitle. This is a very rare error message.

Solution: Verify that the paragraph structure is correct and that only the ChapNum or AppNum tags occur before a ChapTitle.

#### Marker and Related Problems (200-299)

200

“Duplication of Marker #9”

This message means that a single heading or other cross reference destination has multiple #9 cross reference markers attached to it. The SGML only allows one ID per tag. In this case, only the last marker ID value will actually be added to the SGML. This may break some cross references unless fixed.

Solution: Determine which marker is incorrect and remove it.

203

“No Inline type specified”

This message indicates a problem with your specification of an inline media object. The allowed types are SGIVIDEO, SGIRGB, SGIAUDIO, and SGIINVENTOR. It's also possible that there's a problem with your syntax: an inline media object should be specified as

type:referenced_filename

If you leave out the colon or introduce extraneous spaces or mistype the type or filename, you may get an error message.

Refer to “InSight Inline Object Tags” in Appendix A for more information.

Solution: Reformat the paragraph correctly.

204

“No InlineObj for InlineTitle”

An InlineTitle can only appear after a InlineObj paragraph.

Solution: Make sure a valid InlineObj paragraph exists.

210

“Illegal tag in index marker: [tag_name]”

An unsupported character tag was specified in an index term. You can use character tags in index markers, but you can't use any character tags that you couldn't use in ordinary text.

Solution: Remove the unsupported character tag.

211

“Empty index term is ignored.”

Part of an index term marker seems to have no text.

Solution: Check the index term marker to ensure it has the correct text between the index term delimiters.

212

“Only 3 levels of index term nesting is supported”

A single index term can only have three levels of nesting (for example, primary, secondary, and tertiary). This error is caused by having too many `:' delimiters within a single index term.

Solution: Restructure the index term to have, at most, three nesting levels. If a `:' appears in the index term text, and it is not a delimiter, insert a `\' character in front of it.

213

“Only 3 levels of index term 'sort as' nesting are supported”

This is a very similar to error #212.

Solution: Remove the extra `sort as' information from the index term.

214

“Footnote INDEX targets (avoid)”

Index term markers cannot be used within a footnote.

Solution: Remove the index marker from the footnote and move it to another relevant part of the document.

215

“No matching ']' for '[' in [term] The index term will be ignored”

The square brackets within an index term are unmatched. This error makes it impossible to correctly parse the index term.

Solution: Correct the syntax of the index term. Refer to “Cross References” in Appendix A and the FrameMaker documentation for more information on creating index markers.

216

“Fatal index term error in [term] The index term will be ignored”

The index term does not have the correct syntax for an index marker.

Solution: Correct the syntax of the index term. Refer to “Cross References” in Appendix A and the FrameMaker documentation for more information on creating index markers.

220

“Invalid Marker 18 format (EXTREF)”

The content of marker #18 for external book links does not have a space character that delimits the short-title and the ID number. The correct syntax is:

<`target_book_short_title`><space><`target_element_unique_id`>

Solution: Correct the marker #18 content.

221

“Marker 19 occurred without a preceding Marker 18”

A marker type 18 with the correct content to start an external book link must occur before the marker type 19 that is placed at the end of the link text. The proper syntax is:

<marker#18>text<marker#19>

Solution: Make sure the proper markers are in the correct locations and that the document title and the markers are tagged as DocumentTitle.

222

“Marker 17 data required for LaunchWord”

A marker type 17 must have content to create the launchable link. The preferred syntax is:

Launchword:`app`:`parms`

Solution: Correct the marker #17 content. Refer to “Creating Links to URLs” in Chapter 3 for more information.

230

“Illegal page number cross reference”

A cross reference that shows only the generated text of a page number is useless within an online display environment. The link is broken and should be replaced with a more appropriate cross reference type.

Solution: Use a different cross reference format.

231

“Unknown cross reference type: [cross_ref_type]”

A currently unsupported cross reference type was encountered by the translator.

Solution: Change the cross reference to a supported type as shown in Table 3-2.

232

“Footnote XREF targets (avoid)”

You can't make a footnote the target of a cross-reference.

Solution: Move the cross reference to point to content outside of the footnote.

233

“Possible unused Frame Target [marker_content]”

The indicated FrameMaker target probably doesn't have anything pointing to it, or a marker #9 was encountered that doesn't have the five unique ID digits at the beginning of the string. It will be impossible to create a cross reference to that destination.

Solution: Remove the unused marker and double-check that the cross reference markers are set up correctly.

234

“Illegal EXTERNAL REFERENCE file name”

A problem occurred when creating an external book link.

Solution: Ensure the external cross-reference link has been established correctly or use the preferred linking method with Markers 18 and 19.

### XML and xsltproc errors

XML and xsltproc errors will occur rarely, when FrameMaker templates are used inapproriately. If an error occurs, use the context of the document provided in the error message to locate and fix that area of the FrameMaker document. Then rebuild the book.

### Unknown Errors

If the translator gets completely confused, it prints an error message that looks something like this:

    ch2.sgm: <UNKNOWN.ERROR>

This type of error is called an unknown error and seldom provides a helpful error message. The report lists the page number (for the FrameMaker document) on which the error occurred.

The translator generates an “unknown error” message when the file conforms to the DTD (and is therefore structurally legal) but a problem exists anyway. Several different (but rare) conditions can cause this error. The problem is usually located in the object immediately proceeding the `<UNKNOWN.ERROR>` tag; examine the `.sgm` file to see exactly where the `<UNKNOWN.ERROR>` message occurred.

To fix an unknown error, open the FrameMaker file, go to the page number indicated in the error report, and look for anything that you think might be causing a problem. Here are some things to look for (in order of likelihood):

- Review the list in “Tagging FrameMaker Files” in Chapter 3. Make sure you haven't violated any of these rules.

- Examine any unusual order of elements. For example, if you put a Figure directly after an Example—or a TextInd, Example, or Code directly after a Note—you'll get an error message.

- Read and follow the guidelines in “Tagging FrameMaker Files” in Chapter 3. Problems often arise from errors in figures and in tables.

## Checking for Display Problems

After your book builds with no errors, bring it up in a web browser as described in “Viewing a Built Book” in Chapter 5 and scroll through it carefully. Here are a few things to review:

- Do the links work? Do they take you to the right places? If you find a broken cross-reference, check to make sure it's correctly formatted in the FrameMaker file (see “Creating Online Links” in Chapter 3 for instructions).

- Are the Table of Contents, List of Figures, List of Tables, and Index correctly formatted? If not, try deleting those files and replacing them with the appropriate template files from the SGI Book Building templates.

- Do all figures appear in the online text? If not, make sure that you set them up correctly (according to the instructions in Chapter 4, “Working With Figures”). If figures do appear, do they display correctly?

[2] For books using the mif2sgml translator, see Chapter 4, “Finding and Fixing Online Book Errors,” in the -001 version of this book, IRIS InSight Professional Publisher User's Guide.

Prev | Table of Contents | Next
Chapter 5. Building Online Books |  | Chapter 7. Creating Online Help