Troubleshooting Publishing Errors

We get a number of support calls regarding publishing problems and some of these issues are easier to track down than others. Often the error message can provide the clues required to isolate where the problem is occurring - such as building the index - but it doesn't provide enough information on what the exact problem is. There are also a number of error messages that are very general "catch all" errors that can occur for any number of reasons. Some of these are a little like saying "an error has happened", so we need to look more at the circumstances of where it occurs.

These are some basic steps you can take to help identify and narrow down the problem:

Step 1. Check the publishing log

Each time a Book is published, a log file is written. This log shows a detailed account of the publishing process, from inserting each topic and file object, through applying the styles or creating the stylesheet, to creating and compiling the project (dependent on the format being published). It includes warning messages and errors that are encountered, and can be used to identify where a problem has occurred. The log displays in the right hand pane while the document is being published, and is also written to a text file which can be opened later from your \AuthorIT V4\Logs folder.

If the error occurs during the 'Inserting Topics and Graphics...' stage of the publishing process, by opening the log once the error had occurred, the last object listed will generally be the one causing issues.

However, if the error has occurred at a later stage - such as when resolving hyperlinks or creating the index - this does not generally provide the clues required to narrow down the exact object.

Step 2. Look at where the error occurs

The stage the publishing process is at when an error occurs will often give a good indication of where the problem lies. For example, if an error occurs during 'Resolving References and Footnotes' when publishing to Word or on 'Adding Hyperlinks' when publishing to HTML, it indicates a problem with a hyperlink setting. If an error occurs on building the Index, it is an Index setting or an Index Entry causing the problem. Try removing the Index temporarily, or building the Index from only topic headings (and not index entries) to confirm this. Sometimes you may have a circular reference within your Index Entries - with Entry A referencing Entry B, and Entry B referencing Entry A. These entries then get into a loop on publishing - as they continue to reference each other - until Author-it gives up and throws an error.

Step 3. What has been changed recently?

If the error has only just started to occur, it is usually because something has changed. If you've made a lot of changes it's not always easy to determine which change sparked the problem, but in some cases if you've only made a few changes it may be obvious. You may have changed a setting on a hypertext link template, or added several new index entries. Use the Object Search to determine what has changed since you last published successfully.

Step 4. Trial by elimination

You can also create small test books to narrow down which object/s are causing the problem - although this is really a process of trial by elimination. For example, create a book for each section/chapter and publish each one separately. If the error occurs in just one section, break that section down further, and so on. Use the Object Duplicate function to create test books without having to make changes to the real one.

What Next?

Having determined the object/s that is causing the problem, you then need to identify why. Sometimes you can open a Topic and quickly see there is something that is not quite right. Maybe some unusual formatting that doesn't seem to come from an Author-it style. Text may show using a different font or bold or italic attributes but if you check the status bar in the Topic Editor, a character style has not been applied. If this is the case, you can usually correct the problem by:

Selecting the entire topic text (Ctrl + A),
Cutting the text (Ctrl + X),
Saving the topic,
Pasting the text back into the topic using the right-click Edit > Paste as Text option, then reapplying correct styles and saving the changes.

In other rare cases, relationships to other objects have been lost. For example, text may contain a link to a hyperlink that does not exist. If these cases, if you open the topic and click the text where the link appears to be, there are no hyperlink object details showing in the status bar. To correct this, remove the link and recreate it.

Understandably, this does not cover all possible scenarios. There can be many reasons an error occurs and we just can't list them all. Don't be too afraid to experiment, but if you do so, do it in small steps. Make one change, and publish. If that doesn't correct the problem, restore the change and make another. Keep track of the changes you've made so you can backtrack if necessary. Alternatively, experiment with a copy of your library until you're satisfied you've found the solution. This way if things don't work, you can easily delete the test library and start again with another copy. Just make sure you don't delete your real library!