PDF Profiles

A PDF profile contains information used when creating a PDF. See PDF creation for information about PDF creation.

To examine, modify or create profiles, select the File » PDF Profiles... menu item to open the profile editor.

PDF profiles are stored in the TopLeaf repository. The title bar of the editor shows you the path to the file containing the profiles.

If you select a different repository in the Preferences dialog you must close and reopen the profile editor to see the profiles for the new repository.

TopLeaf provides a standard PDF profile. When the profile editor is opened for the first time in a repository, it will show the standard profile. At this point, the file containing the profiles does not exist in the repository (even though its path appears in the title bar of the editor). The file is not created until you make a change and press OK.

To create a new profile, press the Add... button and enter a name which is different from any of the existing profiles. A profile name may contain letters, digits and the characters ‘-’, ‘_’ and ‘.’. To remove a profile, select it from the list and press Remove. The profile called default may not be removed — this ensures that at least one profile is always available.

To close the profile editor, press OK to save your changes, or Cancel to discard them. Press Apply to save changes without closing the editor.

A profile is defined by the information on the tabs described below.

The General tab

The PDF Version allows you to set the level of the PDF standard used.

The Full compression checkbox causes some of the metadata to be stored in a compressed format (the page content is always compressed), resulting in smaller files. This option is only available for version 1.5 or later.

If the Enable bookmarks checkbox is not ticked the PDF will not contain bookmarks. This does not affect the table of contents extraction.

The Viewer Preferences fields allow you to set information that tells a viewing application how to display the PDF. See “Viewer preferences” for a description of the available preferences.

The Fonts tab

The options on this tab relate to font embedding. Select one of the following embedding options:

  • Never means that no fonts will be embedded in the PDF.

  • Default to not embed means that, in general, fonts will not be embedded in the PDF. The only exceptions are fonts that have Always embed selected in their font configuration entry.

  • Default to embed means that, in general, all fonts will be embedded in the PDF. The only exceptions are fonts that have Never embed selected in their font configuration entry.

  • Always means that all fonts will be embedded, even the core PDF fonts. See “PDF and fonts” for more information.

You may also select the way TopLeaf behaves when a font cannot be embedded:

  • Ignore means that a failure to embed a font is not reported in any way.

  • Warn and continue means that all embedding failures are reported in a log file, but the PDF is created. A PDF with font embedding failures can only be viewed or printed successfully if the fonts are available on the computer on which the PDF is being viewed.

  • Do not create PDF means that any failure to embed a font is fatal and that the PDF will not be created. A log file listing the embedding errors will be produced.

The Links tab

This tab controls the creation of hyperlinks in the PDF.

If the Enable links checkbox is not ticked the PDF will not contain any hyperlinks. This does not affect formatting applied by mappings that create hyperlinks (in other words, the text of the link will appear the same, but the link will not be active).

A hyperlink which does not have a destination is sometimes referred to as a broken link. When TopLeaf fails to find the destination for a link, it does not activate the link in the PDF. This means that nothing will happen if the user clicks on the corresponding text or image. In fact, there is no indication to the user that this is a broken link, unless a specific format has been applied to the text of links.

One of the following actions can be selected for links with no destination:

  • Ignore means that broken links are simply ignored.

  • Warn and continue means that all broken links will be reported in a log file, but the PDF will be created.

  • Do not create PDF means that any broken link will be regarded as a fatal error and prevent the PDF from being created. A log file listing the broken links will be produced.

Check the Annotate bad links with comments box to produce a PDF comment for each bad link that contains the target identifier that could not be found. This can be very useful when trying to determine why the target could not be found. This is only relevant when the “Warn and continue” option above is selected, since the other options do not result in a PDF with broken links.

The Security tab

This allows you to restrict what end users can do with the PDF.

TopLeaf supports 128-bit password encryption. In order to enable security controls, a master password must be supplied. See “Security settings” for more information about security settings.

[Note] Note

The security provided by these options is relatively weak, and is not intended to be a substitute for a full Digital Rights Management or strong encryption solution.

In particular, these options rely on the PDF viewing application honoring the security settings. While the Adobe Reader® application operates according to the PDF standard, there is no guarantee that other PDF readers will do the same.

Content Suppression

You can assign a content level to content in a document by using the <content-properties/> command in your mappings. The content suppression options can then be used to prevent content with a content level greater than a given value from appearing in the PDF.

Set the Content level value to enable content suppression. All text and graphics with a security level greater than this will be excluded from the generated PDF. The default value of “9” indicates that no content is to be excluded.

You can set the Replacement graphic field to the full path of a graphic to use in place of any graphic that is excluded from the PDF. The graphic will take up the same space as the excluded graphic. If it is larger than the excluded graphic it will be scaled to fit and centered in the space available. If it is smaller, it will appear at its natural size, centered in the available space. If the excluded graphic is rotated, the same rotation will be applied to the replacement graphic.

[Note] Note

Content exclusion is only applied to text and graphics. Other output (for example horizontal rules) is not affected.

The Images tab

This allows you to create a number of image filters that are used to transform images before incorporating them into the PDF.

The top list shows the filters that apply when the current profile is being used. The bottom list shows the filters that apply to all profiles.

When an image is processed TopLeaf looks for a filter with a matching type. The profile filters are checked first, followed by the global filters. The first matching filter is used. If no matching filter is found the image is processed normally.

To create a filter press Add... and enter the following details:

  • The Name can be used to describe the purpose of the filter.

  • The Input is the type of image to be processed.

  • The Output is the output format created by the filter. This may be the same as the input format.

  • The Working directory is the path to the directory in which the command is run. This may be blank.

  • The Command contains the command to be executed. Each line is passed as a separate argument. The first line must be the path to the command executable. The strings {input} and {output} must be present and are replaced by the paths to the input and output files.

For example, the following filter uses the ImageMagick software to change the resolution of PNG images (the ImageMagick application must be downloaded and installed separately).

The Colors tab

This allows you to select how colors are processed when creating the PDF.

Select the desired item from the Color model drop-down. The default value (rgb) uses the colors specified in TopLeaf as device-dependent RGB colors. If a color palette exists for the stylesheet, the RGB values defined in it will be used instead.

The cmyk model uses the color palette to find a CMYK equivalent for each color. A warning will be given if there is no palette or if a color has no CMYK value defined.

[Note] Note

Selecting the cmyk color model does not have any effect on graphics. It is only used for converting colors selected in the mappings.

The grayscale model can be used to create a PDF that only contains black, white and shades of gray. If the stylesheet has a color palette the grayscale value defined for the color (if any) is used. Otherwise a map is used to specify how each color is converted.

Select Convert images to grayscale to convert all images to grayscale form. Note that this will cause vector images to be converted into a bitmap format.

[Warning] Warning

The default grayscale image conversion may cause a decrease in quality and remove transparency information. If the result is unacceptable you can use an image filter to apply a different conversion.

Tick the Use default map box to use a map that gives good results under most circumstances. You can also enter relative weights for each of the red, green and blue components in the color — a greater weight results in a lighter shade of gray for that component.

[Note] Note

The grayscale map is not used for converting graphics — these are converted by calculating a standard luminance value for each pixel.

The separation model uses the spot color definitions in the color palette if they are defined. Otherwise it will try to use CMYK colors. If neither of these are found, or if there is no color palette, RGB colors will be used.

The Page tab

This tab allows you to set page boundaries using the page size, the print area and the crop area.

For each of the boundary boxes select one of the page areas to define it, or select Undefined. You can also apply offsets to the selected area by entering an offset definition in the following field (see below for a description of how to specify offsets).

[Note] Note

To get correct results, make sure all page types used on a page define the same print and crop areas.

Offset definition

An offset definition consists of one, two or four measurements separated by spaces. Each measurement is a number optionally followed by a unit of measure. Both positive and negative values are allowed. If no unit is given, points are assumed. Valid units are “pt” (points), “cm” (centimeters), “mm” (millimeters), “pc” (picas) and “in” (inches).

The interpretation of the measurements is as follows:

  • A single measurement is applied to all four sides.

  • If two measurements are present, the first is applied to the top and bottom and the second is applied to the left and right sides.

  • Four measurements are interpreted as top, left, bottom and right offsets.

In all cases, a positive measurement has the effect of increasing the size of the area, and a negative value decreases it. For example, a positive value for the top offset moves the top edge up, while a positive bottom offset moves the bottom edge down.

The Watermarks tab

This allows you to control whether one or more watermarks are applied to each page when this profile is selected.

The list on the left shows all of the available watermarks. Click on a watermark to display a preview in the right-hand pane. The checkbox next to a watermark shows whether it is applied by this profile.

To create a new watermark, press the Add... button and fill in the details. To change a watermark, select it and press Edit... or double-click it.

A watermark may not be removed if it is applied by any profiles. To remove a watermark, uncheck its name for all of the profiles, then select it and press Remove.

The following options in the Edit Watermark dialog control the appearance of the watermark. All measurements are a number of points.

Select Over content to draw the watermark on top of the page content, or Under content to draw it underneath.

The Horizontal alignment determines the position of the watermark when it is smaller than the available space on the page. When it is wider than the available space, it is scaled down to fit.

The Horizontal padding determines the amount of space reserved on the left and right sides of the page. Increasing this space decreases the space available for the watermark.

The Vertical alignment and Vertical padding have the same meanings as the above, but in the vertical direction.

The Rotation is expressed as a number of degrees in the counter-clockwise direction.

The Pages field allows you to select the pages on which the watermark will appear. See below for more information.

The Opacity is a measure between 0 (fully transparent) and 1 (fully opaque). If the watermark is drawn above the page content, it determines to what extent the content is obscured by the watermark.

The Blending mode determines how a watermark drawn above the content combines with the content. An appropriate blending mode allows you to have an opaque watermark without obscuring the content beneath it. See the PDF Reference for more information about blending modes.

Text Details

The Text, Font and Size fields determine the text to be displayed. If a line of text starts with the string “META:” the remainder of the line is used to locate a metadata variable with that name. If found, the line is replaced by the metadata value; if not found, the line will become empty.

The Line space determines the extra vertical space between each line of text.

The Color specifies the color used to draw the text. It is either a color name or a string of the form #RRGGBB, where each of the red, green and blue values are 2 hexadecimal digits.

The Outline width is the width of the line used to draw the outlines of the characters; if this is zero the characters are filled.

Image Details

For an image watermark you must specify the absolute path to the file containing the image. The Browse button opens a file selection dialog to help you locate the file.

Watermark Page Selection

The page selection for a watermark determines on which pages the watermark will appear. The selection is based on page number, where the first page in the PDF has number “1”.

The possible values are:

  • A blank string means that the watermark will appear on all pages.

  • The string “odd” means that the watermark will only appear on odd-numbered pages.

  • The string “even” means that the watermark will only appear on even-numbered pages.

  • A single number means that the watermark will appear on that page number only.

  • Two numbers separated by “-” means that the watermark appears on the corresponding inclusive range.

  • A number followed by “+” means that the watermark appears on that page and all following pages.

[Note] Note

The watermark page selection uses the page number of the PDF being created; it does not use page numbers assigned by the mappings.

This is particularly important if you are creating a PDF from a part of a document. The page selection always treats the first page in the PDF as page number one, even if it is not the first page of the document.