Running a Profile and examining results

pdfToolbox uses Profiles to perform quality control and/or to fix PDF documents. This article explains how you use those Profiles and how you can drill-down in the results of using such a Profile.

Running a Profile to analyze or fix a PDF document

To use a Profile, first open the Profiles Window by using the "Tools" > "Profiles" menu item.

  1. Select the Profile you want to use.
  2. The "Analyze" button only does quality control and will never change the PDF document: in the Profile you have selected, it will only execute the Checks. This can be used to check whether a PDF document is good or not.
  3. The "Analyze and fix" button also runs the Fixups of the selected Profile in addition to the quality control. The document may be modified in this case.

The Result window – examining processing results

While pdfToolbox Desktop is processing the PDF document, you'll see a progress window that informs you of which Fixups have been run or what messages are reported about the PDF document. When processing is done, this progress window becomes the "Result" window you see below.

The Result window shows:

  1. The result of processing. In this case a red cross indicating there was at least one error detected.
  2. All Fixups performed by the Software are listed. It could be assumed that this list only displays the Fixups that were necessary for the profile execution. This is very often the case. However, there are a small number of Fixups that are always listed in the results window. The reason for this will be explained in the next section "Fixups that are always listed in the Result window".
  3. An error issued by preflight Checks in the Profile. An error is something that likely will be a problem later on. It's something that needs to be fixed.
  4. A list of all warnings issued by preflight Checks in the Profile. A warning is an item that may be an issue but doesn't have to be. It's something that needs to be checked.

When pdfToolbox processes a PDF document using a Profile, it will first run all Fixups in the Profile and then run the preflight Checks. If something in the PDF document was wrong, but it could be fixed by a Fixup, it won't appear in the warnings or errors. If a warning or an error is reported, it's because they could not be fixed by the Profile and they need to be dealt with otherwise.

Fixups that are always listed in the Result window

When a profile is applied to a document, all Fixups performed by the software are listed in the Results window. This list often assumes, that it is meaningful in terms of whether the execution of a Fixup was necessary. Of course, this assumption is true in most cases. However, there are a small number of Fixups that are always executed by the software, regardless of whether they are necessary or not. These Fixups are therefore displayed each time in the Results window. For example, single  Fixups from the "Fonts" or "XMP Metadata" area may be affected.

The list of executed Fixups can therefore not always be interpreted as a reliable information about actual changes to the PDF.

The technical background is as follows: As already mentioned in chapter 2.1, an internal analysis is performed before a Fixup is executed, which checks whether a Fixup is necessary. This analysis requires a certain amount of time. To keep the processing time of the profile as short as possible, certain Fixups are always applied to the PDF file immediately, since the previous analysis would take more time than simply executing the Fixup.

To find out, whether the PDF file has been modified by a Fixup and the result file matches all requirements, a Check can be configured which verifies the result.

Drilling down to what causes warnings and errors

It's often helpful to know exactly where on the page a warning or error occurs.

  1. Via the triangle next to the warning or error message, further details can be viewed. Different information appears depending on the category.
  2. Under "Trigger values" a list of the objects that caused the respective warning or error message is displayed.
  3. The Overview is always part of the Results window and can be viewed independently of the Fixups and Checks. It contains detailed information about the PDF document (page geometry, color spaces, fonts, images and much more).
  4. You can click the "Show in Snap" button to open a separate window where just the object causing the warning or error is shown.
  5. A preflight report can be generated using the "Create Report..." button. You can find more information about this topic here.