Troubleshooting books

Even though you can update and generate a book without error messages, the book may still have some problems that need correcting.

Generated file is empty
Make sure the name of the generated file is preceded by a generated files icon in the book window. If it isn’t, the file was added as a document to the book file rather than as a generated file (see Create a book). When a file is added as a document file, FrameMaker won’t generate it. Also check that the setup of the generated file is correct.

Slow performance
To improve performance, open as many files in the book as possible before you use Edit > Update Book or File > Import > Formats in a book window. After using the command, save all the files in the book.
Note: In addition, if you experience slow performance while working with books, minimize or remove the Show/Hide Conditional Text panel from your workspace.

Chapter starts on wrong side
You need to correct your documents’ pagination.

Interpreting error messages

The Book Error Log reports all errors that occur when you apply a command to a book. In addition, many error messages contain hypertext links so that you can click the message in the Error Log to display the location of the error.

Unresolved Cross-Refs
The Book Error Log lists all files that contain unresolved cross-references.

Inconsistent Show/Hide Settings, Inconsistent Use Condition Indicators, or Inconsistent Condition Indicator
The indicated file contains conditional text settings that differ from those in the previous file in the book. You can make the settings in each file the same (by using Special > Conditional Text) or you can update the settings throughout the book at once. To do this, change the settings in one file and then use File > Import > Formats to apply the settings to the entire book.

Inconsistent Numbering Properties
The numbering properties specified in the component are different from the book’s numbering properties. The book’s numbering properties override those of the document. See Document and page numbering.

Inconsistent Color Settings
The indicated file contains color separation settings or color definitions that differ from those in the previous file in the book.

Couldn’t Open File
The Book Error Log will indicate if the file was saved using an older format, if it used unavailable fonts, or if it cannot locate the file. For more information on the problem, open the file to see the alert message that appears.

Book Not Self-Consistent
The contents of generated files, the page count, or cross-references continued to change while generating and updating files in the book. For example, if a book contains both a list of markers and an alphabetical list of markers, and if both contain hypertext links, the number of markers grows each time the files are generated. If this happens, move one of the generated lists out of the Include scroll list when you use the Generate/Update command again.

Inconsistent Element Boundary Settings
In a structured book, element boundaries are showing in some files in the book but not in others. Fix the settings in individual files to make them consistent.

Troubleshooting TOCs and lists

Minor problems in the source document may cause corresponding problems in the list. For example, an incorrectly tagged paragraph may cause an extra entry to appear in the list or to be missing from it. Or an empty paragraph may cause an extra line to appear in the list.

Extra entries or lines
Incorrect formatting in the source document can cause extra paragraphs to appear in a list such as a table of contents. To correct this, do the following:
  • If the list contains an entry that doesn’t belong there, check the corresponding paragraph tag or marker type in the source document and either apply a different format to the paragraph or change the marker type.

  • If the list contains an extra line with only a page number, delete the corresponding empty paragraph in the source document. If you need extra space between paragraphs in the source document, use the spacing properties of the paragraphs’ formats rather than insert an empty paragraph.

Missing entries
To include entries that appear in the source document, but not in the list, do one of the following:
  • If all entries with a particular paragraph tag or marker type are missing, make sure the Include scroll list in the Set Up dialog box contains the correct items.

  • If an occasional entry is missing, check the tag of the corresponding paragraph or element, or the type of the corresponding marker in the source document. If any of these are incorrect, the information won’t be included in the list.

Split entries
A multiline heading in the source document can be a problem if the line breaks were created by pressing Return so that each line is a separate paragraph. The list will contain an entry for each paragraph in the heading. Fixing the list requires using only one paragraph for the heading in the source document.

Avoid using forced returns in a heading; forced returns appear in the generated TOC. Instead, to force a heading to break into two lines where you want, change the right indent of the heading paragraph in the source document. If the heading is centered, you may want to change both the left and right indents. You can also use nonbreaking spaces to force a heading to break acceptably.

Incomplete entries (unstructured documents)
When an element contains more than one paragraph, the list includes an entry for only the first paragraph. A multiline heading in the source document can be a problem if each line is a separate paragraph.

Avoid using forced returns in a heading; forced returns appear in the generated TOC. Instead, to break a heading into two lines (while still including all of its text in the list), use nonbreaking spaces to force a break. Or you can adjust the right indent for the heading to force a break, or the right and left indents if the heading is centered, though this will be a format rule override.

Note: Be aware that these techniques create overrides to both paragraph styles and element definitions. As such, they may not be retained when importing formats or element definitions, or when changing the context of the element by editing other parts of the structured document.

Incorrect pagination (books with xml components)
If you have a mix of structured xml and unstructured files in a book, sometimes the page numbers are incorrect when you generate a PDF. This problem could be because the pagination information for xml files is obtained from the template and the template could have a dual pagination setting.

To avoid this problem, always open the xml files and then update the book. This way all the components in the book have correct pagination information and the PDF that you then generate also has correct page numbers.

Bad line breaks
Bad line breaks in the list or its source document may separate information that belongs together in the list. To correct this, do one of the following:
  • Change the characters after which FrameMaker allows line breaks. For example, FrameMaker normally allows a line break after an en dash (–). To disallow breaks after an en dash, use Format > Document > Text Options.

  • In the special text flow on the reference page, use nonbreaking spaces between the text and page number for each entry so that a page number does not appear on a line by itself. See Edit special text flow for a list or index.

Disappearing titles
A title you entered may disappear when you regenerate, unless you give the title a paragraph format.

Disappearing formatting
If your formatting changes aren’t retained when you regenerate (see Formatting lists and indexes), do the following:
  • If you changed the filename or location of the list, change the name and location back. FrameMaker won’t find any formatting changes unless you save the list in the same folder as the source document and use the filename that FrameMaker assigns.

  • To retain paragraph and character format changes, store them in the list’s Paragraph Catalog or Character Catalog, making them available the next time you generate the list.

  • To retain other changes, make them in the special text flow, as described in Edit special text flow for a list or index.

Troubleshooting indexes

Missing entries
If an entry is missing entirely from the generated index, do the following:
  • Check whether the corresponding marker (or marker element) is an incorrect marker type. You can do this by generating a list of markers that includes all marker types and then searching the list for the entry you want.

  • Check whether the corresponding marker (or marker element) is in hidden conditional text by using Special > Conditional Text to show all conditional text, and then generating the index again.

  • Check whether the marker (or marker element) was deleted accidentally.

Entries containing double question marks
Double question marks (??) in a page range indicate that FrameMaker can find only one of the two markers that define the range. If you see double question marks, do the following:
  • Check that neither marker (or marker element) is missing.

    Missing <$startrange> and the resulting page range
  • Check that the spelling, punctuation, and capitalization of the marker text match exactly.

    Inconsistent spelling and the resulting page range
  • Check that <$startrange> appears in the first marker (or marker element) and that <$endrange> appears in the second marker (or marker element).

    <$endrange> comes first and causes the resulting page range

Missorted entries
Most sorting problems are the result of incorrect marker text. If you see missorted entries, do the following:
  • Check that the colons and semicolons are used correctly. If a semicolon appears where a colon belongs, two main entries appear rather than one subentry. If a colon is missing, a subentry appears incorrectly as a main entry.

    Missing colon and the resulting missorted entry
  • Check that sorting information is present and correct, and appears between brackets ([ ]) at the very end of the marker text (see Change sort order). For example, if you want to sort a cross-reference as the last subentry, the sorting information in the marker text for it should end with :zzz.

    Missing :zzz and the resulting missorted entry
  • If sorting errors occur in a pattern—for example, if all numeric entries appear at the end of the index rather than at the beginning—check that the sorting information in the special text flow on the reference page is correct.

Page numbers with See or See also cross-references
A cross-reference index entry may incorrectly contain a page number. Make sure that <$nopage> appears at the beginning of the marker text for the cross-reference entry.
Missing <$nopage> and the page number wrongly appears

Bad line breaks
If entries break between numbers in a page range or between the end of the entry and the first page number, do the following:
  • Change the characters after which FrameMaker allows line breaks. To disallow line breaks after certain characters, such as an en dash (–), use Format > Document > Text Options.

  • To force the end of an entry to appear on the same line as the page number, use a nonbreaking space, an en space, or an em space as the separator between them.

  • If you specified in the special text flow on the reference page that spaces or hyphens appear between page numbers in a range, make sure they are nonbreaking (see Edit special text flow for a list or index).

  • Change the volume or chapter numbering for the source document’s page numbers (see Set up numbering). If the book’s pages are numbered by chapter (11, 12, …, 21, 22, …),‑‑‑‑ the volume or chapter number should be followed by a nonbreaking hyphen.

Bad line breaks

Disappearing titles
A title you entered may disappear the next time you generate the index, unless you follow the steps in “Add a title or other static text to lists and indexes”.

Disappearing formatting
If your formatting changes aren’t retained when you regenerate (see Formatting lists and indexes), do the following:
  • If you must rename a generated file, do so using the book window. FrameMaker will rename the file in the book window and on disk.

  • To retain paragraph and character format changes, store them in the index’s Paragraph or Character Catalog, making them available the next time you generate the index. For details, see “Redefining (updating) formats”.

  • To retain other changes, make them in the special text flow, as described in Edit special text flow for a list or index.