DaVince Tools Converters

Version: 3.0

Part of DaVince Tools
Web Site: www.davince.com

Last Modified: November 16, 2004

Introduction

All "DaVince Tools" converters contain a number of common features. Common command line syntax, initialization file use, common profile options and a common scripting language allow for a user to become familiar with all converters easily and also allows the tools to be easily integrated into the Windows interface application, wdavince.exe.

Common Command Line Syntax

The command line syntax for all the converters is the same:

(Please note that the square brackets "[" and "]" specify optional parameters; do not enter the brackets as part of the command)

converter [-1] [-c commandfile] [-f] [-i key:value [-i key:value]] [-o outputfile] [-p profile] [-r] [-s] [-?] [file1 file2 ...]

Arguments:

converter: The name of the converter: bmp2pdf, file2pdf, jpeg2pdf, tiff2pdf or txt2pdf

-1: (numeric "one") Create one PDF file for each text file specified on the command line (one to one relationship). For each TIFF file specified, a PDF file is created in the same directory with the same name except with a ".PDF" extension. A PDF file is not created if one already exists and is newer than the corresponding text file. To force a PDF file to be created, use the "-f" option. If "-1" or "-2" options are not used, then the default is to take all specified files and combine them into a single PDF file (many to one relationship). The behavior of the "-o" option changes when using the "-1" option, as described below.

-2: Create one PDF file for each subdirectory (many to few relationship). For each directory specified on the command line, each subdirectory in that directory is scanned and all text files in that subdirectory are converted to a single PDF file. The behavior of the "-o" option changes when using the "-2" option, as described below. If the "-r" (recursion) option is used, then also convert all files in the subdirectory tree.

-c: Process commands in the specified command file. When using this argument, files and directories can be specified via a file instead of on the command line. Click here for more info on command files.

-f: When used with the "-1" option, force overwriting an existing PDF file. By default, a PDF file may not be created with the "-1" option if the TIFF file is unchanged since the last time the PDF file was created.

-i: Specify Info dictionary attribute values like title and author of document. The following attributes are available for use:
 
 
Attribute
Description
Author The name of the person who created the document.
Keywords Key words associated with the document.
Subject The subject of the document.
Title The title of the document.

Note that the attribute names are case sensitive (first character in uppercase). This option can be specified multiple times when setting multiple dictionary attribute values. To specify an attribute along with its data, separate the two with a colon ":". You will need to enclose the string in quotes if there are spaces in the data. For example, to set the title of a document to "The Declaration of Independence", use the following parameter:

-i "Title:The Declaration of Independence"

In addition to these tags, custom tags can be used with this option; however, Acrobat Reader will not recognize them. The "CreationDate" and "Creator" attributes are automatically filled in by the program and cannot be overridden with this option.

-o: Specify the PDF filename to create, or the directory to store the newly created PDF if the "-1" or "-2" option is used. If a filename is specified, the ".pdf" extension should be included. If this option is not specified, the directory where the text files are found is used if the "-1" or "-2" option is used, otherwise, the filename in the table below in the current directory is assumed:
 
Converter Default Filename
bmp2pdf
bmp.pdf
file2pdf (Plus version) file.pdf
jpeg2pdf jpeg.pdf
tiff2pdf tiff.pdf
txt2df text.pdf

This option is required when converting files from CD ROM using either the "-1" or "-2" options, since the default directory is not writeable.

-p: Specify a profile to use in the creation of the PDF file. Profiles contain conversion information such as margin and font settings and reside in the "txt2pdf.ini" file located in either the directory where the executable file resides or the windows base directory (typically "C:\WINDOWS" for Windows 9x, "C:\WINDIR" for Windows NT). If the file is present in both directories, the file located in the windows base directory takes precedence. The default profile "default" is used when this option is not specified.

-P: Specify a profile parameter on the command line. This allows one to specify profile parameters without the need for a command file. Specify the parameter in "key:value" format. Place quotes around the parameter if spaces are in the value. This option may be specified multiple times on the command line.

-r: When a directory is specified, search subdirectories (recursive search).

-s: Sort the filenames specified on the command line in alphanumeric order before processing them. Note that when a directory is specified on the command line, files in that directory are always sorted.

-?: A brief summary of arguments is displayed.

[file1 file2 …]: Specify one or more files to convert. Wild card characters such as "*" and "?" may be used.

The Initialization File

The initialization file is a text file that stores one or more profiles containing conversion options. This allows one to create a variety of profiles with different conversion definitions. To specify a profile on the command line, use the "-p" option. The profile can be picked easily from the Windows interface program after the appropriate converter is chosen. From a DaVince Command File, use the "profile" command to specify the profile.

"DaVince Tools" recognizes two predefined profile names. The "default" profile is used when no other profile name is specified. The "_common" profile is used to define a parameter for all profiles. This profile is applied prior to any other profile. This allows an option to be set globally. For example, the following _common profile:

[_common]
annotationtext=The data contained in this file is the property of ABC Inc.

will by default create this text annotation on all profiles, unless the option is overridden in a profile using the "annotationtext" option with a different value.

The profile name is enclosed in square brackets (i.e. "[default]"), followed by a list of profile options. The profile name is case sensitive, however, the profile options are not ("[default]" and "[Default]" are not the same profile). Profile names like [_common], which begin with an underscore, are hidden in the Windows interface program but are still valid profile names. The following is an example of a profile definition:

[default]
description=Default Profile
bookmark=yes
openaction=fit
compression=yes

Multiple profiles can exist in the file. The "-p" command line option and the DaVince command file command "profile" determines which profile the program will use. Profile names are case sensitive. If no profile is specified on the command line, the default profile ("[default]") is used.

Several options can appear after the profile line. These statements have the following syntax:

setting=value

Where setting is the name of a valid setting (see below for a list of common options) and "value" is the value for the setting. Depending on the option, "value" can be a number, a string or a Boolean value. The following values are all valid for a Boolean value:
 
 
Valid True Values Valid False Values
True, T, On, Enable, Yes, Y False, F, Off, Disable, No, N

These values are case insensitive (i.e. both "true" and "TRUE" are valid).

Each converter uses its own initialization file. The name of this file is the name of the converter with an ".INI" file extension. Thus these names will be:,
 
Converter Name Initialization Filename
bmp2pdf.exe
bmp2pdf.ini
file2pdf.exe
file2pdf.ini
jpeg2pdf.exe jpeg2pdf.ini
tiff2pdf.exe tiff2pdf.ini
txt2pdf.exe txt2pdf.ini

 

The location of the initialization file is typically in the same directory as the executable file. "DaVince Tools" ships with sample initialization files for all converters in the "exe" directory, which contains both the executable programs and the ".ini" files. The initialization file can also be located in the Windows' directory (typically "c:\windows" for Windows 9X and "c:\winnt" for Windows NT/2000/XP). Putting the initialization file in the Windows directory may make sense for those who want to use the same profile options with multiple versions of the converter. The initialization file in the Windows directory takes precedence if the file is found in both directories.

Common Profile Options

Although there are a number of unique profile options unique for each converter, there is a large number of profile options that are common to all converters. These profile options are defined either in the .ini file for the appropriate converter, defined in a DaVince Command File (DCF) using the param statement (i.e. "param bookmark true) or defined on the command line using the "-P" (uppercase P) option. The following table describes these profile options (option names are case insensitive):
 
Options Data Type Description
AnnotationAppearance String  PDF page description of annotation. Use to specify font color. Default: "0 0 1 rg" (blue font color). For more information refer to the Adobe PDF Reference Manual for information on page descriptions.
AnnotationFont Fonts: Courier | Courier-Bold | Courier-BoldOblique | Courier-Oblique | Helvetica | Helvetica-Bold | Helvetica-BoldOblique | Helvetica-Oblique | Times-Roman | Times-Bold | Times-Italic | Times-BoldItalic | ZapfDingbats

Encodings: Default | WinAnsiEncoding | MacRomanEncoding | PdfDocEncoding

 The name of the font and optional encoding. The font name can be the name of any of the 14 base fonts for Adobe reader. The font name is case sensitive (default font is Helvetica).

An optional encoding can be specified. The encoding name is also case sensitive (default encoding is WinAnsiEncoding).

AnnotationFontHeight Number Height of annotation, in points. Default: 10
AnnotationOptions  allpages=true|false Comma separated options used to define how the annotation is created. Currently, one option is available:

allpages - Set to true if annotation is to appear on all pages, false if the annotation is to appear on the first page only

Default: allpages=false

AnnotationRectangle Number Number Number Number Rectangle definition of where the annotation will be placed on the page, in points. Define the lower left and upper right corners of the rectangle such as "x1 y1 x2 y2".

Positive #'s are relative to the bottom left corner of the page. Negative #'s are relative to the upper right corner.

Default value: 18 -38 -18 -18

AnnotationText String Text to be used for the annotation. Leave blank if no annotation is needed.
Bookmark Bool When true, create a bookmark for each file converted. The default is false.
BookmarkDelimiter*
String
Specify character to use to create the bookmark hierarchy. The default is "\".
BookmarkDisplay*
Open or Close
This is used when creating a bookmark hierachy. When "Close" is used, the bookmarks to follow will initially be in a closed position, requiring a double click to open them. The default is "Open"..
BookmarkFilenameExtension Bool When true, include filename extension in the bookmark name. Otherwise, ignore it. The default is false.
Compression Bool When true, compress the page description (image data is always compressed). The default value is false.
DeleteDirectories Bool WARNING: Use this option with caution. Specifying this option, along with "DeleteFiles" set to true, will delete the subdirectories where the original files reside. The directory is deleted only if the directory is empty after deletions from "DeleteFiles" occurrs.

Default: false

DeleteFiles Bool WARNING: Use this option with caution. Specifying this option will delete the original file after conversion to PDF. This option is typically used in a watch folder type of command file.

Default: false

Description String Description of profile. This description is displayed in the Windows version of "DaVince Tools"
FileMatch String This parameter allows setting a default file match pattern when specifying a directory to convert. This is a comma delimited list of file matching patterns. The default setting is:

txt2pdf: "*.txt,*.bat,*.ini"
tiff2pdf: "*.tif,*.tiff"
jpeg2pdf: "*.jpg, "*.jpeg"

FlateLevel Integer: 1-9 An integer value specifying the compression level for the Flate algorithm. The Flate algorithm is used for compressing streams, images and thumbnails when the compression option is enabled. Setting this value to 9 results in the best compression but also takes the longest in computation time. A value of 1 provides the best performance but little or no compression. A value of 6 is regarded as a value that provides decent compression with adequate performance . The default setting is 9.
GarbageCollection * Bool Enables and disables garbage collection. Garbage collection is done just prior to writing the PDF file to remove unreferenced information in the PDF file. It is required for the txt2pdf option PageTrim. The default is false.
Info String Use this parameter to set Info tags in the PDF file, like Title, Subject and Author. Info tags are case sensitive. Info tags specified on the command line will override these settings. This parameter is typically used in the _common profile to globally set Info tags for all profiles. Multiple tags are separated by commas. For example:

info=Title:DaVince Tools Generated PDF File,Author:DaVince Tools
 
 

Also refer to the command file interface for another method of specifying Info tags.

OpenAction Fit, FitH, FitV, None This parameter describes how to view the first page of the newly created PDF file when opened. Choices are "Fit" to fit entire page, "FitH" to fit the horizontal width of the page, "FitV" to fit the vertical width of the page, or "None", which defaults to the setting defined in the PDF viewer. The default setting is "None".
Thumbnail
Bool
Create thumbnail images for all image converters. Note that this will increase processing time, even when the "Archive" option is set to false in tiff2pdf. The default is false.
VerboseLevel Number Alters the amount of output that is generated. Two levels are currently defined:

1: display only messages about files that are converted (suppress "skipping" messages). This mode is used with watch folder command files.

2: display all messages

Default:2

WebOptimize*
Bool
When enabled, the resulting PDF file will be optimized (also called linearized) for web viewing.
*New in 3.0

About DaVince Tools:

Visit the DaVince Tools web site at http://www.davince.com for the latest version of this software and the latest documentation. DaVince Tools is shareware and software registration is urged if you find these programs useful. You can register the software on-line at http://www.davince.com.

DaVince Tools was written in C++ using the DaVince Class Library, written by the same author as this program. The DaVince Class Library is a C++ library for developing PDF and TIFF applications. Contact the author at info@davince.com for more information on the availability of the class library.