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:

--report=<type>,<trigger>,[options,]<PATH=path>

You can use --report as often as you like in one run to create different type of reports.

Parameters

type
see "Report types"
trigger
see "Report triggers"
options
see "Further options"
path
see "Report path"

Report types

XML
XML report
XSLT=<type>
XSLT report, type can be a custom type or one of the types delivered with pdfToolbox CLI ("compacttext" or "compacthtml")
MASK
PDF report, problems highlighted by transparent masks
COMMENT
PDF report, problems highlighted by annotations
LAYER
PDF report, problems separated on layers
INVENTORY
PDF report which lists all resources used in the PDF file
COMPARE
PDF compare report
SUMMARY
PDF overview report
TEMPLATE=

Report triggers

ALWAYS
Always create report (default)
ERROR
Create if at least one problem with severity "Error" was found
WARNING
Create if at least one problem with severity "Warning" was found
INFO
Create if at least one problem with severity "Info" was found
HIT
Same as INFO,WARNING,ERROR

Further options

OVERVIEW
Include overview for PDF reports
DOWNSAMPLING [#<PPI>]
Downsample images in PDF reports of type Mask, Layer and Comment to the given resolution (Default: 150 ppi)
HIDEERROR
Hide all checks with severity "Error" (not for type "Layer")
HIDEWARNING
Hide all checks with severity "Warning" (not for type "Layer")
HIDEINFO
Hide all checks with severity "Info" (not for type "Layer")

PDF layer report options

ICCNAMES
Create layer for all ICC color space names
SPOTNAMES
Create layer for all spot color space names
FONTNAMES
Create layer for all font names

PDF inventory report options

FONTS
Include fonts
COLORS
Include colors
SHADES
Include smooth shades
PATTERNS
Include patterns
IMAGES
Include images, optional number of pixels like IMAGES_100
FORMXOB
Include Form XObjects
XMP
Include XMP
XMPADV
Include XMP advanced

XML report options

ALL
Include all ressources (Default)
NONE
Include no ressources
IMAGES[#<NUM>]
Include first <NUM> images
FONTS[#<NUM>]
Include first <NUM> fonts
PAGES[#<NUM>]
Include first <NUM> pages
COLORS[#<NUM>]
Include first <NUM> color spaces
SHADES[#<NUM>]
Include first <NUM> smooth shades
PATTERNS[#<NUM>]
Include first <NUM> patterns
FORMXOB[#<NUM>]
Include first <NUM> Form XObjects

Ink coverage options for XML reports:

INKCOV
Include ink coverage for every page
INKCOVRES[#<PPI>]
Rendering resolution used for ink coverage calculation (Default: 300 ppi)
INKCOVBOX[#<Box>]
Defines the PageBox (as ArtBox, TrimBox, BleedBox, CropBox or MediaBox) which will be used for rendering (Default: CropBox)

Report path

PATH=<path>

path
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

TEMPLATE=<path>
path
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:
../var/Reports/Templates.

Maximum number of pages

--maxpages

Maximum number of pages (default: 1000) - after this limit only pages that have problems will be stored.

Hits per page

--hitsperpage=<number>

Maximum number of hits per page reported. Every check will be considered individually.

Parameters

number
maximum number of hits per check per page that will be reported

Hits per document

--hitsperdoc=<number>

Maximum number of hits per document reported. Every check will be considered individually.

Parameters

number
maximum number of hits per check per document that will be reported

Setting the report language

-l --language=<language>

Sets the desired language for report files.
Parameters

language
language of report files
en
English
de
German
fr
French
es
Spanish
it
Italian
pt
Brazilian Portoguese
cz
Czech
da
Danish
nl
Dutch
fi
Finnish
ja
Japanese
ko
Korean
no
Norwegian
pl
Polish
sv
Swedish

Example

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:

  •     Server/CLI:

../cli/var/Reports/Templates

  •     Desktop/PlugIn:

<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

index.html
the template in HTML format
manifest.xml
a XML file which defines information needed as content for the report, to be delievered by the pdfToolbox engine
/css
contains a style sheet
/fonts
contains used fonts
/img
contains used images
/scripts
contains used JavaScripts

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

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.

Basic document information as well as all results of the processed profiles are provided by default. Other parts like a preview image, comparision images or an XML report can be also requested here. Even a XML report can be ordered to enable picking up additional information about the PDF or executed fixups or checks using JavaScript.

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>

Purpose

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>

Purpose

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>

Purpose:

Include compare tree if comparison resources are used inside index.html.

Parameters

resolution resoultion used in ppi for rendering the comparision

Keep the temporarily generated files

<x:settings>
<x:keeptemp>true</x:keeptemp>
</x:settings>

Purpose

Temporarily generated files like the filled index.html, CSS-files, images,

XML-reports and used JavaScripts will not become deleted after finnishing the PDF report.

Parameters

false files become deleted (default)

true files will not become deleted

Creating a XML report for additional content

<x:results>
<x:xmlreport path="xml/report.xml"
inkcovres="72" inkcovbox="TrimBox"/>
</x:results>

Purpose

Requests a XML report of the performed profile to extract additional information using JavaScript which can be used in the report.

Determining the ink coverage will only take place if one of the respective parameters exists.

Parameters

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 index.html of the default "overview" template references a stylesheet, two JavaScripts as well as a number of images.

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.

For adding more functionality it is recommended to do this in new, own JavaScript files, which have to be linked in the <index.html> of course.

Examples for template modification

callas software is providing a number of sample templates, which can be downloaded using the following link:

http://www.callassoftware.com/manuals/callas_Tutorial_HTML-reports.zip

This package contains samples as complete template folders including comments in the HTML-, CSS- or JavaScript-files and the result as a PDF.

0 Comments

Send Your Comment

E-Mail me when someone replies to this comment