Get PDF

Command line:
tlapi ‑cGETPDF [‑psPhase] [‑u] [‑snShow] [‑PsProfile] [‑esLinkParts] [‑nnOpts] ‑osPdfFile sPart
Library call:
nStatus = TLgetpdfEx (sPart, sPhase, nUpd, nType, (char * ) NULL, sLinkParts, sProfile, sOpts, sPdfFile, nShow)
Library call:
nStatus = TLgetpdf (sPart, sPhase, nUpd, nType, (char * ) NULL, sLinkParts, nOpts, sPdfFile, nShow)
Scripting call:
sPdfFile = GetPDF (sLocation)

Function

Create a PDF version of the page images in a partition. The partition must have been composed (for example, by calling the Compose call).

[Warning] Warning

Any errors or warnings when creating a PDF are written to a log file in the same directory as the output file. The log file has the same name as the output file but with extension “.log” replacing the extension (if any) of the output file. Any existing file with this name will be silently removed.

[Note] Note

The TLgetpdf library call is deprecated and may not be supported in future versions of the API.

Arguments

sPart

The path of the partition from which to generate the PDF. The scripting call uses the Partition property to determine the partition to use.

sPdfFile

The full pathname of the output PDF file. If the file already exists, it will be replaced. If the file does not exist, it will be created.

sPhase

The partition phase from which to take the data. One of INITIAL, PUBLISH, UPDATE or CURRENT. Defaults to PUBLISH, so for a non-looseleaf job it is usual to select INITIAL.

The scripting call uses the Phase property to determine the phase to use.

nUpd

If non-zero, only changed pages are included in the PDF. In the command line version, use the ‑u flag to request only changed pages.

The scripting call uses the value of the ChangedPages property to control this behavior.

Note that hyperlinks and bookmarks are disabled when the PDF contains only changed pages. A meta data variable can be used to enable bookmarks in this case.

nType

Not used. Always pass zero for this argument.

sLinkParts

A string specifying one or more partitions which may contain endpoints of links in the generated PDF.

The string can be either a partition path or a pattern containing wildcard characters in the last component. For example,

UserManual/*

can be used to match all partitions in the UserManual publication. The list of partitions generated from a pattern match will never include the partition specified by the sPart argument.

See below for more information on cross-PDF linking.

sProfile

The name of the profile that determines options for creating the PDF. Pass NULL for this argument to use the default profile.

sOpts

A string specifying processing options as described below.

These options override those specified by the profile. Pass NULL if you do not wish to set any options.

To set processing options for the scripting call, use the Set Transform Property method.

nOpts

A number specifying processing options as described below.

To set processing options for the scripting call, use the Set Transform Property method.

nShow

The Windows showmode for the typesetting progress display. By default, the typesetting dialog will be displayed.

The only useful values are SW_NORMAL (1) and SW_MINIMIZE (6). The latter causes the progress window to run minimised. There is no way to prevent the creation of a window.

This parameter is ignored on Unix.

sLocation

This applies to the scripting interface only. This determines where the PDF file is created:

  • If null or the empty string, the file is created in a directory designated for temporary files.

  • If it is the path to an existing directory, the file is created in this directory.

  • Otherwise, the file is created using sLocation as a path. Any existing file with this path will be overwritten.

For additional command line arguments see “Common Flag Arguments”.

Scripting Call Return

The return value is a string containing the path to the PDF file. This is always an absolute path. It is also available as the value of the OutputFile property.

An empty string is returned if any problems occur when creating the PDF. If these are non-fatal errors and a PDF has been created, the OutputFile property will be non-empty and will contain the path to the PDF.

The PdfLog property contains the path to the log file containing warning and/or messages from the PDF builder, or the empty string if there were no messages.

Cross-PDF Linking

It is possible to create links from the generated PDF into PDFs generated from other TopLeaf partitions. The same target matching scheme used for internal links is used; if a match cannot be found in the list of internal targets, a matching target is sought in one of the partitions specified by the sLinkParts argument.

For links to work at runtime, the PDF generated must have the same name as the partition which generates it. For example, the PDF generated from “UserManual/Reference” must be called “Reference.pdf”. When the PDFs are distributed, they must all be in the same directory for the links to function correctly.

Processing Options

Processing options are specified by a string of the form:

name1=value1 name2=value2 ...

where each name is a property name, and value is a string containing the value to use. For a list of property names and the values see the “pdf” section of the table in the Set Transform Property method.

The property values can be enclosed in single or double quotes. Quotes are removed before interpreting the values. The following are therefore all equivalent:

compress=smallest

compress="smallest"

compress='smallest'

The command line call and the (deprecated) TLgetpdf library call use the numeric value in the nOpts argument to specify properties. The argument is formed by adding one or more of the entries in the following table. You can select at most one value from each of the groups.

For example, a value of 6 (= 2 + 4) will produce an uncompressed PDF with embedded fonts (ignoring any font embedding errors).

Group Value Description
Compression 0 Use the compression scheme that will produce the smallest file
1 Use the fastest compression scheme
2 Do not produce a compressed file
Font embedding 0 Don't embed fonts
4 Embed fonts; ignore any errors
8 Embed fonts; produce a warning for any error
12 Embed fonts; abort if there is an error
Bookmarks 16 Disable bookmark creation
Links 0 Ignore broken links
32 Create a warning for each broken link
64 Abort if there are any broken links (do not create a PDF)
96 Don't create any links
Broken link marking 128 Insert a comment (PDF annotation) for each broken link
Security 2048 Do not allow copying or extraction of text
4096 Do not allow printing

Note that font embedding can be controlled for individual fonts using the font configuration. The settings for a particular font always override the settings in the processing options.

Examples

Command line:

tlapi ‑cGETPDF ‑pINITIAL ‑oC:\mydoc.pdf manuals/topix/vol1

Library call:

status = TLgetpdfEx("manuals/topix/vol1", "INITIAL", 0L, 0L, NULL, NULL,
              "print", "links=badignore", "C:\\mydoc.pdf", SW_HIDE);

Scripting call:

topleaf.SetTransformProperty("pdf", "profile", "print");
pdf = topleaf.GetPDF("C:\\Temp");