Creating a report using Profiles
You have a wide variety of options for creating a report. Only adding -r to your call would create an XML report next to the input PDF file, no matter if any hits occurred. You can modify this behavior by the following parameters:
You can use --report as often as you like in one run to create different type of reports.
||see "Report types"
||see "Report triggers"
||see "Further options"
||see "Report path"
||XSLT report, type can be a custom type or one of the types delivered with pdfToolbox CLI ("compacttext" or "compacthtml")
||PDF report, problems highlighted by transparent masks
||PDF report, problems highlighted by annotations
||PDF report, problems separated on layers
||PDF report which lists all resources used in the PDF file
||PDF compare report
||PDF overview report
||PDF report based on HTML templates
||JSON report (starting with pdfToolbox 13.0)
||Always create report (default)
||Create if at least one problem with severity "Error" was found
||Create if at least one problem with severity "Warning" was found
||Create if at least one problem with severity "Info" was found
||Same as INFO,WARNING,ERROR
||Include overview for PDF reports
||Include overview based on HTML templates for PDF reports (starting with pdfToolbox 10.0)
||Downsample images in PDF reports of type Mask, Layer and Comment to the given resolution (Default: 150 ppi)
||Hide all checks with severity "Error" (not for type "Layer")
||Hide all checks with severity "Warning" (not for type "Layer")
||Hide all checks with severity "Info" (not for type "Layer")
||Language for the respective report, will overwrite general --language option of the CLI (starting with pdfToolbox 10.0)
PDF layer report options
||Create layer for all ICC color space names
||Create layer for all spot color space names
||Create layer for all font names
PDF inventory report options
||Include smooth shades
||Include images, optional number of pixels like IMAGES_100
||Include Form XObjects
||Include XMP advanced
XML report options
||Include all ressources (Default)
||Include no ressources
||Include first <NUM> images
||Include first <NUM> fonts
||Include first <NUM> pages
||Include first <NUM> color spaces
||Include first <NUM> smooth shades
||Include first <NUM> patterns
||Include first <NUM> Form XObjects
Ink coverage options for XML reports:
||Include ink coverage for every page
||Rendering resolution used for ink coverage calculation (Default: 300 ppi)
||Defines the PageBox (as ArtBox, TrimBox, BleedBox, CropBox or MediaBox) which will be used for rendering (Default: CropBox)
||Path to report file (if not defined, report is created next to input file)
When defined, this must always be the last element of the --report parameter.
PDF report based on HTML template
||Path to template folder (or respective index.html directly)
PDF overview reports are created based on a style defined in a HTML/CSS template. A predefined
template can be found in the Server/CLI path:
Maximum number of pages
Maximum number of pages (default: 1000) - after this limit only pages that have problems will be stored.
Hits per page
Maximum number of hits per page reported. Every check will be considered individually.
||maximum number of hits per check per page that will be reported
Hits per document
Maximum number of hits per document reported. Every check will be considered individually.
||maximum number of hits per check per document that will be reported
Setting the report language
Sets the desired language for report files.
See article "Command line options for multi-language support" for a list of fully localized languages and how to extend incomplete translations or how to modify strings.
||language of report files
pdfToolbox --language=fr --report=ERROR,WARNING,LAYER,OVERVIEW,PATH=<path to report file> <profile> <PDF file>
pdfToolbox --report=ERROR,WARNING,TEMPLATE=OVERVIEW,PATH=<path to report file> <profile> <PDF file>
HTML-based custom reports
To adjust PDF-reports easily, HTML-based custom reports can be used.
The visual appearance is controlled by a HTML-Template and Custom Style Sheets (CSS), while the reported details are directly requested from pdfToolbox or (optionally) parsed from an internally created XML-report.
Structure of related files
A predefined HTML-template is contained in all installer packages for Desktop and Server/CLI.
This predefined template can be found in:
<User Preferences>/callas software/pdfToolbox <version>/Reports/Templates
(using Desktop/PlugIn, a HTML-based report must have been generated at least once, in order to have these these files created)
The predefined template contains several folders and files
||the template in HTML format
||a XML file which defines information needed as content for the report, to be delievered by the pdfToolbox engine
||contains a style sheet
||contains used fonts
||contains used images
It is highly recommended to create a copy of the original template in a separate folder when starting to adjust a HTML-template based report.
The manifest.xml defines the set of information to be provided by the pdfToolbox engine. This information will be used to to fill up the details in the report based on the HTML-Template.
The display name in the user interface is defined here as well.
For developing purposes, the internally generated, filled HTML representation of the report can be maintained to review changes in the template files also in a browser.
The HTML converter is using WebKit, so it is recommended to use Safari (or Chrome, which is based on a spin-off of WebKit) as a browser.
Request basic informations about PDF
<x:dict> <x:overview/> </x:dict>
If contained, document information and results of the performed profile will be available for using them in the HTML template.
Preview images of pages
<x:results> <x:preview resolution="150" page="1"/> </x:results>
Rendering of images of one or more pages for visual represenation of the PDF in the report.
Visual comparision of original and processed file
<x:compare> <x:document_a resolution="20"/> <x:document_b resolution="20"/> <x:diffresult resolution="20"/> </x:compare>
Include compare tree if comparison resources are used inside index.html.
resolution resoultion used in ppi for rendering the comparision
Keep the temporarily generated files
Temporarily generated files like the filled index.html, CSS-files, images,
false files become deleted (default)
true files will not become deleted
Creating a XML report for additional content
Determining the ink coverage will only take place if one of the respective parameters exists.
inkcovres resolution in ppi, used for determining the effective ink coverage of each page in the PDF (optional, default: 300)
inkcovbox page geometry box of which the effective ink coverage will be determined (optional, default: CropBox)
The HTML template
The HTML template can easily be modified using an appropriate codeeditor or enhanced text-editor.
The provided HTML-template already contains some "dummy" data, which is automatically replaced by actual content when a new report is generated.
So, when doing adjustments to the template with custom profiles and PDF files, it is recommended to keep the temporarily generated files for debugging, as a basis for modifications and their review in a browser.
It is possible to use image formats (like JPEG or PNG) as well as PDFs for positioning visual content like logos. If you want to debug your HTML in an HTML Browser you may want to display an image instead of the PDF reference. You can do this by putting identically named files for images and PDF next to each other. The PDF file must be referenced in the <img> tag in the HTML-template. The usage of PDF files allows for higher quality of logos in the resulting PDF report.
How the HTML-template works
The provided HTML-template contains already all document and processing information which can be supplied directly from the application.
You will find <cals_params.js> and <cals_overview.js> which are used by the engine to create and render the HTML. Please do not modify these files.
Examples for template modification
callas software is providing a number of sample templates, which can be downloaded using the following link:
Custom Dict files
Custom Dict files can be used to add or modify strings that are used in reports. Since pdfToolbox 10.0 it is allowed for custom dicts to cover strings for custom profiles or unknown Dictkeys in a particular language.
Creation of custom dicts
In the following example, a custom dict is created for strings of a non localised language to be added/replaced in a predefined Profile (kfpx). This can be achieved using the command line argument:
--createcustomdict <Path to Profile file>
This creates an XML for the profile (kfpx).
<?xml version="1.0" encoding="UTF-8" ?> <callas> <dict version="3.0" lang="en"> <keys> <group key="P"> <entry key="8_Listpotentialfontproblems"> <value var="long">List potential font problems</value> <value var="short">Lists possible font issues.</value> </entry> </group>
A user can add his own custom language and values (long for Name and short for Comment as in this example).
<?xml version="1.0" encoding="UTF-8" ?> <callas> <dict version="3.0" lang="in"> <keys> <group key="CUSTOMDICT"> <entry key="भारत"> <value var="long">भारत</value> <value var="short">भारतभारतभारत</value> </entry> </group>
On running the profile along with the custom dict set to the XML with overwritten strings and custom language, there is no problem of appearance of DictKeys for unknown languages in pdfToolbox reports:
--customdict=<Path to custom XML file>
./pdfToolbox /Users/List potential font problems.kfpx /Users/pdfToolbox CLI 10/123.pdf --report --customdict=/Users/Downloads/List potential font problems.xml --language=in
Profile name and comment without the appearance of DictKeys in the XML report (other report types will work as well of course):