data-id=acrobat-pdfl-sdk-pdf-creation-settings

Acrobat-PDFL SDK: PDF Creation Settings

The Adobe PDF Creation Settings file format provides a means of storing settings that affect the creation of PDF files. It is based on the settings (.joboptions) files that have been used in all versions of Acrobat Distiller. The format has been expanded so that other applications can share the files and store private settings.

data-id=terminology

Terminology

Adobe PDF Creation Settings files have an extension of .joboptions and have often been called job options files (referring to the Distiller job that converts PostScript to PDF). Creative Suite applications refer to the files as presets. This document refers to the files as settings files.

The individual PDF creation settings themselves are represented in the settings files as key-value pairs. The key is a name and the value can be any data type supported by PostScript or PDF. In previous versions of Acrobat Distiller Parameters, the settings are referred to as parameters. This document refers to them as settings.

data-id=18721

data-id=organization-of-settings-files

Organization of settings files

A PDF creation settings file contains a number of settings. (In the context of Acrobat Distiller, these settings are also referred to as parameters.) Each setting has a name, called its key, and a value, which is data of a defined type. All data types conform to PostScript and PDF syntax, as described in the PostScript Language Reference and the PDF Reference. All applications in the Adobe Creative Suite, version 2.0 and later, as well as Acrobat Distiller, can read and write settings files.

The settings file is a text file, represented in a format that is recognized by a PostScript interpreter. At the highest level, the file consists of two dictionaries that contain key-value pairs representing the settings. The first dictionary is followed by the setdistillerparams operator and the second is followed by the setpagedevice operator.

<<
   key-value pairs representing settings
>> setdistillerparams
<<
   key-value pairs representing settings
>> setpagedevice

setdistillerparams is a Distiller-specific PostScript operator; that is, it may not be recognized by standard PostScript interpreters. The dictionary that is an operand to setdistillerparams contains most of the key-value pairs representing the settings described in this document. For example:

<<
         /ASCII85EncodePages false
         /AllowTransparency false
         /AutoRotatePages /None
         /Binding /Left
         ...
>> setdistillerparams

setpagedevice is a PostScript operator that allows specifying page device parameters (see the PostScript Language Reference for more information). A small number of settings (HWResolution and PageSize) are specified in the setpagedevice dictionary. Unless otherwise specified, this document refers to settings in the setdistillerparams dictionary.

Note

Acrobat Distiller has the ability to process setdistillerparams operators that appear in PostScript files that it is processing. For example, image compression settings can be changed for specific images. See How Distiller processes PostScript files for more information.

data-id=90851

data-id=namespaces

Namespaces

Prior to Distiller 7.0 and Creative Suite 2.0, all parameters were specified at the root level of the setdistillerparams dictionary and were publicly available to Distiller and other applications that used the file.

The concept of namespaces has been introduced to allow settings that are private to one or more applications. Each namespace is conceptually separate, which allows multiple applications to define keys with the same name but different meanings.

A single namespace is represented as an entry whose key is Namespace and whose value is an array of three required strings that represent the following items, in this order:

The following example represents the Common namespace, version 1.0.

/Namespace [ (Adobe) (Common) (1.0) ]

The version number makes it possible for settings to be added to a namespace or for the values of existing settings to change. In the future, a file might also contain the following code, which would have additional entries not part of the original set.

/Namespace [ (Adobe) (Common) (2.0) ]

Applications not supporting version 2.0 would ignore them, while newer applications could use them.

Note

The specification allows more than three elements to be stored in the array. It would be possible to refine namespaces further, as in the following example.

/Namespace [ (Adobe) (CreativeSuite) (2.0) (Professional) ]

data-id=common-namespace

Common namespace

All settings supported by Distiller 7.0 and earlier, and documented in past editions of Acrobat Distiller Parameters, are considered to be in the Common namespace.

The Namespace entry appears in the same dictionary as all the other settings defined for that namespace. Therefore, an entry for the Common namespace may appear in the top-level dictionary in a settings file, as in the following example:

<<
         /ASCII85EncodePages false
         /AllowTransparency false
         /AutoRotatePages /None
         /Binding /Left
         /Namespace [ (Adobe) (Common) (1.0) ]
         ...
>> setdistillerparams

In the top-level dictionary, the Namespace setting is optional. All settings are assumed to be part of the Common namespace. The Namespace key is required in the dictionaries in the OtherNamespaces array, discussed below.

data-id=othernamespaces

Othernamespaces

The OtherNamespaces entry is used to define namespaces other than the Common namespace. Its value is an array consisting of one or more dictionaries representing namespaces. Each of the dictionaries must contain the Namespace key that identifies the namespace, as well as the settings that are part of the namespace.

Three namespaces have been defined to support Creative Suite 2.0:

CreativeSuite (version 2.0): Contains settings that are used by one or more of the suite applications and are not recognized by Distiller.

InDesign (version 4.0): contains settings supported by InDesign alone.

The OtherNamespaces entry can also be used by third parties and OEMs to place their dictionary of private settings.

Here is an example of the OtherNamespaces entry. It contains two namespaces: InDesign and CreativeSuite :

/OtherNamespaces [
     <<
         /AsReaderSpreads false
         /CropImagesToFrames true
         /ErrorControl /WarnAndContinue
         /FlattenerIgnoreSpreadOverrides false
         /IncludeGuidesGrids false
         /IncludeNonPrinting false
         /IncludeSlug false
         /Namespace [
             (Adobe)
             (InDesign)
             (4.0)
         ]
         /OmitPlacedBitmaps false
         /OmitPlacedEPS false
         /OmitPlacedPDF false
         /SimulateOverprint /Legacy
     >>
     <<
         /AddBleedMarks false
         /AddColorBars false
         /AddCropMarks false
         /AddPageInfo false
         /AddRegMarks false
         /ConvertColors /ConvertToCMYK
         /DestinationProfileName ()
         /DestinationProfileSelector /DocumentCMYK
         /Downsample16BitImages true
         /FlattenerPreset <<
         /PresetSelector /MediumResolution
         >>
         /FormElements false
         /GenerateStructure false
         /IncludeBookmarks false
         /IncludeHyperlinks false
         /IncludeInteractive false
         /IncludeLayers false
         /IncludeProfiles false
         /MultimediaHandling /UseObjectSettings
         /Namespace [
             (Adobe)
             (CreativeSuite)
             (2.0)
         ]

Applications that do not recognize the OtherNamespaces entry will ignore its contents but should preserve the contents when saving the settings file (as they should preserve all settings); see Reading and writing settings files.

data-id=18498

data-id=predefined-settings-files

Predefined settings files

Adobe provides a set of predefined PDF settings files or presets that you can use for common scenarios. By means of the user interface (UI) of Acrobat Distiller and the Creative Suite applications, you can create and modify new PDF settings files based on the presets. (You should not actually modify the presets themselves.)

The reference chapters, Common PDF Settings and Other Namespaces, indicate the UI controls, if any, that correspond to each setting. See the Help for these products for detailed information about working with settings files in the user interface.

You can also edit settings files in a text editor. This gives you greater control, because some settings cannot be modified in the UI. However, it also increases the chances of having a settings file that contains syntactic or semantic errors. How applications handle incorrect settings files explains how Adobe applications deal with errors.

data-id=where-presets-are-installed

Where presets are installed

When a user installs Distiller or the Creative Suite applications, a group of presets are installed on the user’s system. These presets can be shared between applications. System preset information describes in detail how applications share information about presets.

Each application displays certain presets by default in its user interface. These are stored in a Settings directory, which is typically at these locations:

Note

The paths specified here represent typical installations. They may differ for specific languages or versions of the products.

Another group of presets is installed in an Extras directory. These can be loaded as needed and typically appear in these locations:

The table Common settings files lists presets that are installed in the Common directory. The table Extra settings files lists presets that are installed in the Extras directory.

In addition to its file name, each preset file has a set of display names, one for each language, that are displayed in the application user interface. The first column of the following tables shows the preset file name (minus the .joboptions extension), as well as the English display name if different.

Specific applications need not display all presets in their user interface. The third column of each table lists the applications for which the file is visible. For details on how applications show or hide presets, see System preset information).

Common settings files

The PDFA1b 2005 CMYK.joboptions and PDFA1b 2005 RGB.joboptions files are identical except for the /ColorConversionStrategy and /PDFXOutputIntentProfile entries. The PDFA1b 2005 CMYK.joboptions file contains lines,

/ColorConversionStrategy /CMYK
 /PDFXOutputIntentProfile (U.S. Web Coated (SWOP) v2)

while PDFA1b 2005 RGB.joboptions contains the lines,

/ColorConversionStrategy /sRGB
 /PDFXOutputIntentProfile (sRGB IEC61966-2.1)

Extra settings files

data-id=26306

data-id=system-preset-information

System preset information

To facilitate the sharing of settings files, Adobe applications use a mechanism, described in this section, to keep track of the following information:

Warning

The Extras folder is in a location parallel to the Settings folder.

This information is equivalent for Windows and Mac OS but is stored in different ways:

On installation or initialization, Adobe applications instantiate this information if it does not exist. Applications should never assume hard-coded paths but use system calls to obtain the information.

The following sections contain system-specific details.

data-id=windows

Windows

In Windows, the top-level registry entry is this setting:

My ComputerHKEY_LOCAL_MACHINESOFTWAREAdobePDF Settings

It contains these key items:

The display names (as with all registry strings) are stored as UTF-16 strings. They may be represented as ASCII or in hexadecimal where ASCII is not suitable. The following example shows the entry for Japanese:

[HKEY_LOCAL_MACHINESOFTWAREAdobePDF SettingsJPN]
         "Standard"=hex:19,6a,96,6e
         "High Quality Print"=hex:d8,9a,c1,54,ea,8c,70,53,37,52
         "Press Quality"=hex:d7,30,ec,30,b9,30,c1,54,ea,8c
         "Smallest File Size"=hex:00,67,0f,5c,d5,30,a1,30,
                 a4,30,eb,30,b5,30,a4,30,ba,30
         "PDFX1a 2001"="PDF/X-1a:2001"
         "PDFX3 2002"="PDF/X-3:2002"
         "PDFA1b 2005 CMYK"="PDF/A-1b:2005 (CMYK)"

data-id=mac-os

Mac OS

In Mac OS, the preferences file is com.adobe.AdobePDFSettings.plist. It is typically stored in /Library/Preferences/. (Developers should use the Mac OS APIs to locate this directory rather than assuming a hard-coded path.)

This file contains a dictionary with at least the following keys:

The following example shows two settings files, Standard and High Quality, that are localized for English and Spanish.

<?xml version="1.0" encoding="UTF-8"?>
 <!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN"
         "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
 <plist version="1.0">
 <dict>
         <key>AdobePDFSettings</key>
         <dict>
                 <key>ENU</key>
                 <array>
                         <string>Standard</string>
                         <string>Standard</string>
                         <string>High Quality</string>
                         <string>High Quality Print</string>
                 </array>
                 <key>ESO</key>
                 <array>
                         <string>Standard</string>
                         <string>Estandar</string>
                         <string>High Quality</string>
                         <string>Impresion de alta calidad</string>
                 </array>
         </dict>
         key>AdobePDFSettingsPath</key>
         <string>/Library/Application Support/Adobe PDF/Settings/</string>
 </dict>
 </plist>

data-id=13147

data-id=reading-and-writing-settings-files

Reading and writing settings files

This section describes the behavior that Adobe applications follow when reading and writing settings files. Many of the principles described are extensions of behavior that has been employed by Distiller since its earliest use of .joboptions files.

data-id=compatibility-strategies

Compatibility strategies

Applications should provide default values for all settings that are meaningful to them and not present in the settings file. When rewriting a settings file, applications should preserve all settings:

Some settings have been deprecated and replaced with new settings. Applications should recognize the deprecated versions, if possible, and use them for processing if the functionality is still available. When re-writing files containing such settings, the new variant should be written in addition to, or as a replacement for, the old setting. For an example, see Using the compliance checking settings.

Different applications may use different settings for similar functionality. For example, Distiller uses settings in the Common namespace to perform color conversions. The Creative Suite applications have a larger set of options for color conversion, provided by settings in the CreativeSuite namespace. For maximum compatibility with Distiller, the Creative Suite applications write out the most closely matching Common settings when saving settings files. See Using the color conversion settings for details.

data-id=how-applications-handle-incorrect-settings-files

How applications handle incorrect settings files

A settings (.joboptions) file can be incorrect in two primary ways:

Distiller treats files containing invalid types or values in one of three ways, depending on the settings that are invalid:

The following types of errors are defined for the Creative Suite:

data-id=78550

data-id=how-distiller-uses-adobe-pdf-settings

How Distiller uses Adobe PDF settings

Acrobat Distiller differs from the Creative Suite applications in that it creates PDF files by processing PostScript files. This section provides some information that is specific to the operation of Distiller.

Note

Distiller also provides an API by which programmers can automate its operation. For details on automation methods, see the Distiller API Reference.

data-id=distiller-initialization

Distiller initialization

Distiller initialization is controlled by the file distinit.ps, which is executed once at Distiller startup. As part of the initialization process, all of the files in the Distiller Startup folder are executed. Example.ps is one such file.

You can add as many other startup files as you want inside the Startup folder. Those files are executed by distinit.ps during initialization.

Note

The files in the Startup folder are not executed in any specific order—not alphabetically, nor in any other predictable order. For that reason, it is best to add all extra initialization code to the Example.ps file to ensure that it all runs in order.

data-id=45049

data-id=how-distiller-processes-postscript-files

How Distiller processes PostScript files

Distiller may process one or more PostScript files during a single job:

Distiller contains a PostScript 3 interpreter with two Distiller-specific operators:

<</CompressPages true>> setdistillerparams

Where the value of a key is another dictionary, provide the keys you want to set in that dictionary. For example:

<</AutoFilterGrayImages true /GrayACSImageDict <<
  /QFactor 0.25 /HSamples [1 1 1 1] /VSamples [1 1 1 1]>>
  >> setdistillerparams

Where the value of a key is another dictionary, currentdistillerparams returns the key-value pairs in that dictionary.

To enable PostScript files containing the currentdistillerparams or setdistillerparams operators to be used on PostScript devices such as printers that do not implement these operators, you must add the following definitions to the beginning of the file:

/currentdistillerparams where {pop}
 {userdict /currentdistillerparams {1 dict} put} ifelse
 /setdistillerparams where {pop}
 {userdict /setdistillerparams {pop} put} ifelse

This PostScript code sequence uses the existing currentdistillerparams and setdistillerparams, if present. If not, it defines currentdistillerparams to return an empty one-element dictionary, and setdistillerparams to be a NULL operation.

PostScript language programs that use these operators must not assume that any particular key is present in the dictionary returned by currentdistillerparams, or that setdistillerparams has any particular side effects.

data-id=68813

data-id=modifying-settings-during-the-job

Modifying settings during the job

The prologue, PostScript, and epilogue files may themselves contain setdistillerparams operators that override the initial values of the settings as specified in the settings file (or through the default values). The parameters remain in effect for the duration of the current save level. (See Section 3.7.3 in the PostScript Language Reference for a discussion of the save and restore operators.) At the end of the current job, Distiller restores the values to those present before the job began.

Settings specified in the settings file cannot be modified if the LockDistillerParams setting is true. In addition, a number of settings cannot be modified during a job using setdistillerparams. Their values are always taken from the settings file or the default values:

Settings that cannot be modified during a job

Three of the settings in this list (DoThumbnails, Optimize, and/or CompressObjects) are not used until the post-processing step of distillation.

The remaining Distiller settings can be changed during a job using setdistillerparams. One exception is that PreserveFlatness cannot be changed in the middle of a page. Its value must be set before any marks are created on the page. For example, when the following PostScript command sequence is distilled, the value in the .joboptions file will be honored and the changes indicated by setdistillerparams will not be used:

1 1 moveto 1 2 lineto
 << /PreserveFlatness false>> setdistillerparams
 20 setflat

Any attempt to change PreserveFlatness after any marks are drawn on a page is ignored.

data-id=using-distiller-to-combine-postscript-files

Using Distiller to combine PostScript files

Note

Adobe recommends that the Acrobat 7.0 feature Create PDF from Multiple Files be used to combine PostScript and/or PDF files together into one PDF.

Distiller can combine two or more PostScript files to produce a single Adobe PDF document. If the PostScript files have embedded font subsets, Distiller gives the resulting PDF file only one subset for each font. This is much more efficient than creating a set of several PDF documents with duplicate font subsets.

The Acrobat installation provides two files you can modify to combine two or more PostScript files to create a single PDF:

These files should be located in these directories:

Follow the instructions in the sample files. The PostScript files are combined in the order in which they are listed. Edit the files in a text editor or word processor, and save the modified files under a new name, as text, with a .ps suffix.

You can then use Distiller to convert the combined file to PDF. You can also place the file in an In folder to be converted later.

The conversion settings used are those listed in the Default Settings pop-up menu in the Acrobat Distiller dialog box.