This chapter describes the errors that can occur when FrameMaker files are converted to SGML format for online viewing. 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.
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 error files. 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.)
Depending on the specific make command you run, you can generate a number of different error files. (See Chapter 5, “Building Online Books,” for more information on make commands.) The .full and .err files in this list are the most useful files for error tracking:
A .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.
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 somewhere it's not supposed to be (such as a HangingList paragraph tag before the ChapTitle tag), they produce an error message. The .sgm file in Example 6-1 shows what error messages look like within an SGML 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 be used only for sub-steps within a step in a numbered list. (See the annotated chapter template file, /usr/share/Insight/templates/frame/IPTemplate/samples/IPChap.doc, for more information on which structures are legal in a document and which aren't.)
The listing in Example 6-1 represents the .sgm 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 for your convenience.
<!-- Produced by version 3.11 (09/11/95) of SGI Frame/SGML translator --> <CHAPTER LBL="1"><TITLE>About the Mottled Oyster</TITLE><PARAGRAPH>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 <COMMAND>G&T</COMMAND> (Gin & Tonic; see the G&T(1) reference page for details). If you read this tutorial carefully, you're sure to have a <GLOSSARYITEM>jolly good time</GLOSSARYITEM> with the mottled oyster. After a few hours with this tutorial you will be able to use the <COMMAND>oyster</COMMAND> command to do your work more quickly and efficiently. You will learn</PARAGRAPH> <BULLETLIST><BULLET><PARAGRAPH>how to prepare your files for bunging into <COMMAND>oyster</COMMAND></PARAGRAPH> </BULLET> <BULLET><PARAGRAPH>general rules to avoid aunts and other threats</PARAGRAPH> </BULLET> <BULLET><PARAGRAPH>the correct intonation for phrases like</PARAGRAPH> <BULLETLISTIND> <!-- ERROR: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "1" UID = "324242" TEXT = "“tally ho!”"--> <BULLETSQUAREIND><PARAGRAPH>“tally ho!”</PARAGRAPH> </BULLETSQUAREIND> <!-- ERROR: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "2" UID = "324246" TEXT = "“hey what?”"--> <BULLETSQUAREIND><PARAGRAPH>“hey what?”</PARAGRAPH> </BULLETSQUAREIND> <!-- ERROR: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "3" UID = "324243" TEXT = "“old bean”"--> <BULLETSQUAREIND><PARAGRAPH>“old bean”</PARAGRAPH> </BULLETSQUAREIND> </BULLETLISTIND> </BULLET> <BULLET><PARAGRAPH>how to request information from a butler</PARAGRAPH> </BULLET> </BULLETLIST> <PARAGRAPH>To use this tutorial you need a basic understanding of these items:</PARAGRAPH> <HANGLIST><HANGPAIR><HANGITEM>cow creamer</HANGITEM> <HANGBODY><PARAGRAPH>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.</PARAGRAPH> <PARAGRAPH>Of course, you must beware of Modern Dutch cow creamers posing as eighteenth-century English cow creamers.</PARAGRAPH> </HANGBODY> </HANGPAIR> <HANGPAIR><HANGITEM><COMMAND>vi</COMMAND> text editor</HANGITEM> <HANGBODY><PARAGRAPH>Allows you to edit text using arcane and cryptic commands.</PARAGRAPH> </HANGBODY> </HANGPAIR> </HANGLIST> <PARAGRAPH>You might want to look at a copy of the <DOCTITLE>Code of the Woosters</DOCTITLE> when you're finished with this tutorial.</PARAGRAPH> </CHAPTER>
The usual method of finding such errors is to look at the .err output files after running 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.
You can see from the example in “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.”
The short_title.full file provides a complete list of all the errors, warnings, and link problems in your book. This list consists of three separate kinds of reports: the translation error and warning report (one for each FrameMaker file), the link QA report file (a single report for the entire book), and 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.
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: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "1" UID = "324242" TEXT = "“tally ho!”"--> <!-- ERROR: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "2" UID = "324246" TEXT = "“hey what?”"--> <!-- ERROR: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "3" UID = "324243" TEXT = "“old bean”"--> === Mottled_Oyster Link QA report file === Unresolved References present in this book: None External Book References present in this book: None === Mottled_Oyster Glossary QA report file === Unresolved Glossary terms present in this book: ------------------------------------------------ jolly good time
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 just ignore those (but you might want to take an especially close look at pages where warnings occurred when you review the book in IRIS InSight 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: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "1" UID = "324242" TEXT = "“tally ho!”"--> <!-- ERROR: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "2" UID = "324246" TEXT = "“hey what?”"--> <!-- ERROR: (16) The Frame tag BulletSquareInd should not occur in a BULLET - detected on page 1 --> <!-- ERRORLOCATION: PAGE = "1" SRC = "oyster.mif" TAGTYPE = "PARA" TAG = "BulletSquareInd" TAGCOUNT = "3" UID = "324243" TEXT = "“old bean”"-->
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 /usr/share/Insight/templates/frame/IPTemplate/samples/IPChap.doc for more information on which structures are legal in a document and which aren't.
The link QA report is the second report contained in the .full file. It lists unresolved cross references and all externally cross-referenced books (it just lists the books, 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 === Unresolved References present in this book: None External Book References present in this book: None
In this example, there were no unresolved cross-references or externally cross-referenced books.
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 FrameMaker 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 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.
Unresolved glossary terms are words that are tagged with the “GlossaryItem” character tag but have no entry in either the local or the global glossary. Example 6-5 is the glossary QA report for the example FrameMaker file shown in Figure 6-1.
=== Mottled_Oyster Glossary QA report file === Unresolved Glossary terms present in this book: ------------------------------------------------ jolly good time
Resolve such errors by creating an entry in the glossary or by removing the GlossaryItem tag from the word in question.
make book errors (see “make book Error Messages” for details)
MIF-to-SGML translation 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 shortname.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 “Choosing a make Command Argument” explains how to use the make command to generate a specific type of file.
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 error messages and their causes, so look for your error message in that list first. If your error message is not in the list, try and find the problem on your own or call your Silicon Graphics Production Editor for assistance.
Often the problem is easy to spot: an empty anchored frame or a misformatted table, for example. Sometimes, however, the problem is more difficult to find. “Unknown Errors” lists some tips to help you find more obscure errors.
This section contains a sample of known error messages with explanations and suggestions for fixes.
ch1.sgm: <!-- ERROR: INFORMATIVE, HELPFUL ERROR MESSAGE HERE -->
ch4.sgm: <!-- WARNING: STOP YOUR SLACKIN' -->
This type of error is called a known error, because it comes with an informative error message. The messages are listed in numerical order, according to the number in parentheses at the beginning of each message. (The numbers don't mean anything, and not all numbers are assigned to a unique error message; don't worry about gaps in the numbering, or about repeated numbers.) A few error messages don't have numbers assigned; these are listed after all the numbered messages. 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.
<!-- ERROR: (1) Character tag tagname 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. To fix the problem, apply Default Paragraph Font to the whitespace between the two parts of the hanging list.
<!-- ERROR: (2) Maximum number of table footnotes exceeded -->
<!-- ERROR: (3) Illegal structure starting at 'MIFMarker' -->
There is a cross-reference marker in the ChapNum paragraph tag at the start of the chapter being processed. Remove that marker and change any cross-references that pointed to it so that they point to the chapter's ChapTitle paragraph instead. You can't have a cross-reference to a ChapNum paragraph.
<!-- ERROR: (4) Unknown Frame tag tagname encountered - detected on page pagenum -->
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.
If the above two don't work, look for straddled cells in the table, unstraddle them, and search on the revealed cells for unrecognized tags.
<!-- ERROR: (10) Hanglist indent not under Hanging list -->
This error occurs if a FrameMaker tag (such as CodeInd5) that should occur only directly after a HangingList or HangingListInd, occurs somewhere else in a document. Don't try to use the *Ind paragraph tags to create your own indentation scheme; there are rules about what indentation can appear where. (The rules are discussed in the sample chapter file /usr/share/Insight/templates/frame/IPTemplate/samples/IPChap.doc.)
<!-- ERROR: (11) Hanglist not legal in this context -->
<!-- ERROR: (12) Illegal Help Subtopic content, `:' not found -->
id_in_frame_file : title_to_appear_at_top_of_card
This error message indicates that the colon in the middle is missing, so the item can't be parsed correctly. Add a colon to the HelpSubTopic item.
<!-- ERROR: (13) No Inline type specified -->
This message indicates a problem with your specification of an inline media object. The only 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:filename. If you leave out the colon or introduce extraneous spaces or mistype the type or filename, you may get an error message.
<!-- ERROR: (14) Hierarchy problem for PARAGRAPH -->
Unable to create an SGML <PARAGRAPH> tag for a figure definition. This means the figure definition (using the Fig paragraph tag) has been applied somewhere it's not supposed to be, such as before a ChapTitle. You might also get this message if you use a Text tag in an unusual position, such as before the ChapTitle. This is a very rare error message.
<!-- ERROR: (15) Margin figure text/graphic flows not in proper order -->
Margin figures are constructed from two anchored frames appearing at the beginning of a paragraph. The first anchored frame contains a graphic image, and the second (which is optional) contains a text rectangle with a FigTitleMargin paragraph tag. This error message indicates that the order of the two anchors has been reversed. Select the anchored frame for the caption (best to select the frame itself rather than the anchor; it's difficult to select a single anchor because the two appear to overlap), remove it using the Edit > Cut command, place the cursor after the other anchor (you can press the right-arrow key to move forward over the anchor) and paste the caption back in.
If you get a “margin figure” error about a regular (non-margin) figure, you probably made a tagging error. If you attach your anchored frame to anything other than an empty paragraph tagged with the Fig paragraph tag, the figure is treated as a margin figure.
<!-- ERROR: (16) The Frame tag tagname2 should not occur in a tagname1 -->
The FrameMaker tag tagname2 cannot legally occur within the structure denoted by FrameMaker tag tagname1. For example, a DashInd tag does not belong under a BulletSquareInd tag. Note that sometimes items that look fine from an aesthetic point of view nonetheless violate the SGML hierarchy and tagging rules set up by Silicon Graphics' DTD.
<!-- ERROR: (17) Hierarchy problem for tagname -->
The FrameMaker tag tagname cannot produce the corresponding SGML tag in the appropriate hierarchical position. The most common cause of this problem is the placement of the wrong tag at the beginning of a file. For example, a FrameMaker chapter file must begin with the tag ChapNum, followed by the tag ChapTitle.
<!-- WARNING: (18) Possible unused Frame Target (target_ID) -->
The indicated FrameMaker target probably doesn't have anything pointing to it. Although this is not an error as such, it may indicate an obsolete marker or linking error. Because this is only a WARNING and not an ERROR, you can safely ignore it if you wish.
<!-- ERROR: (20) Footnote XREF targets (avoid) -->
<!-- ERROR: (21) Footnote INDEX targets (avoid) -->
<!-- ERROR: (22) Figure Logic Error -->
This message indicates that you've used two anchored frames containing figures before the figure's title or caption. This could happen, for instance, if you place two anchored frames in the same Fig paragraph, before the FigureTitle paragraph. (Note that if one of the frames is tagged as PrintOnly conditional text, this error shouldn't occur.)
<!-- ERROR: (23) Invalid Marker 18 format (EXTREF) -->
<!-- ERROR: (24) Illegal tag in variable tagname -->
<!-- ERROR: (25) Tag 'tagname' is obsolete or print-only -->
<!-- ERROR: (26) Marker 17 data required for Launchword -->
You can allow IRIS InSight readers to launch an executable by clicking on hot text in your document. To do this, label your hot text with the Launchword character tag, then place a FrameMaker Marker of type 17 just before the text. The marker itself must contain text indicating what to launch, in this format:
This error message indicates that the marker is empty or the syntax is incorrect.
<!-- ERROR: (27) Index Format Syntax
<!-- ERROR: (28) Msg without preceding Msg1st -->
<!-- ERROR: (29) 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.
<!-- ERROR: (30) Index Format Syntax: ':' before end tag 'tagname' -->
<!-- ERROR: (31) Footnote paragraph tag usage incorrect -->
<!-- ERROR: (32) Glossary tag usage in this context probably incorrect -->
<!-- ERROR: (33) Cannot process Frame on page pagenum -->
This probably means you have an empty anchored frame on page number pagenum. Import a figure into the anchored frame. See “Working With Figures” for instructions. If a figure isn't ready yet, you can ignore this error message, view your book without figures, and put the figures in later. Another possible cause of this error message is an improperly formatted margin figure.
<!-- ERROR: (34) Cannot process Indirect Frame on page pagenum -->
This indicates that the tools are having a hard time processing a margin figure. When you add a new margin figure and then build your book, FrameMaker sometimes produces MIF for the new anchored frames that the translator can't process. To fix the problem, save your document file as MIF (using File > Save As...), open the new MIF file, and resave it as the original .doc file. Note that this procedure resets the autonumbering for that file; you'll have to use the Generate/Update command from the book file to make autonumbering work properly again.
|Note: This error does not necessarily indicate that the anchored frames that form the margin figure are in the wrong order. Margin frames that are properly ordered can still have this problem.|
<!-- ERROR: (34) Illegal tag in index marker: tagname -->
<!-- ERROR: INTERNAL: Unclosed Tags <TextFlow> -->
This error is usually caused by tagging something that should not be tagged or by not completing a sequence of more than one tag. For example, your file might contain a hanging list that includes a list item without a body or that is not followed by descriptive text.
<!--ERROR: Untranslated Function Character (character_name) -->
This message indicates that you've used a FrameMaker character that the translation tools don't recognize. Search the FrameMaker document for that 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.
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 Appendix A, “Rules to Follow When Using the Templates.” 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 Chapter 3, “Using FrameMaker Files and IPTemplate Features.” Problems often arise from errors in figures and in tables.