# Using Command Files

Version: 2.0.0

Part of DaVince Tools

Last Modified: December 13, 2001

### Purpose

A command file allows a DaVince Tools converter to process command directives from a file instead of the command line. This provides additional capability to DaVince Tools not found when specifying files and directories strictly on the command line. Use of a command file has the following advantages over the command line:

- Specifying files and or directories via a file simplifies the command line syntax and eliminates the problem of exceeding the command line buffer when specifying a large number of files and/or directories.
- A configuration profile can be changed during processing of the command file. Conversely, only a single profile can be specified on the command line.
- An alternate name or alias can be given to a file for bookmark purposes, allowing bookmarks to be created using text other than the name of the file. Specifying a blank name will prevent a bookmark from being created for a particular file.
- The command file can be used as an application programming interface (API) to the DaVince Tools converters. A programmer can write code that generates a command file and then subsequently runs the converter with the generated command file.

The command file is the application programming interface (API) used by the Windows interface application, wdavince, to send commands to a converter.

### Syntax

A command file consists of a series of lines entered in a text file. The file can be created with a standard text editor like Notepad or it can be generated by a program like wdavince. Lines beginning with the pound character ( # ) or the single quote character ( ' ) are considered comments and are ignored. Special consideration is given to the first line in the command file by the Windows program, wdavince. If the first line begins with the two characters "#!" (a comment with an exclamation point as the second character), the text in the line specifies the converter to use when running the command file. For example, if the command file started with the line:

`

#! txt2pdf

`

then wdavince will run the command file against the txt2pdf converter. This technique allows wdavince to save a command file to disk and be able to run it at a later time against the correct converter.

The following commands are valid in the command file:

`

cd create dir echo file info param profile

`

Refer to the Command Description section below for details on the syntax for each command.

Note:

When a filename or directory name is specified as a parameter to one of the commands above, it must be enclosed in quotes if there is a space character included in the name. For example, to convert files in the "My Documents" directory, use the following command: `

# this is the correct way
dir "c:\My Documents

`"

Instead of the following:

`

# this is the WRONG way
dir c:\My Documents

`

### New in This Release

The following commands are new in version 2.0:

`

create echo info param

`

### Command Summary

cd | changes the current directory used by the "file" and "dir" commands
create | Specify the name of the PDF file to create
dir | Convert specified directory
echo | Echo text to the screen
file | Convert specified file
info | Add info strings to PDF file
param | allows configuration parameters normally stored in the .ini file to be included in the command file
profile | Specify the profile to use as defined in the INI file

### Command Description

The following section describes the commands. Command options in square brackets ("[]") are optional. The vertical pipe character ("|") specifies a choice of options. These characters are not actually used in the command.

`

cd directoryname

`

The "cd" command changes the current directory used by the "file" and "dir" commands. This command is useful when many files are contained in a single directory, which alleviates the need to prepend a path name to a file when using the "file" command.

`

create [filename] [1 [force]]

`

This command specifies the name of the PDF file to be created. Alternatively, the command can be used to specify converting the files in a one to one fashion using the "1" option. This is the same as specifying the "-1" option on the command line. By default, the program checks to see if a PDF file has already been created. If it has, and the PDF file date is newer than the original data file, then no PDF file is created. To force the PDF file to be created, even if the data has not changed, specify the keyword "force" after the "1" option.

This command should be specified prior to the `file` or `dir` commands.

Examples:

To convert many files to one to a file named "conversion.pdf", use the following syntax:

`

create conversion.pdf

`

To convert files one to one, forcing a new PDF if one already exists, use the following syntax:

`

create 1 force

`

`

dir directoryname [r]

`

The "dir" command specifies a directory to process. If an "r" is specified for argument 2, then the directory is processed recursively (similar to the "-r" command line option), otherwise, the directory is processed without recursion. Directory names with spaces in them must be enclosed with quotes. If a directory name contains a quote character, the quote must be preceded with a backslash character.

`

echo "text to display"

`

or

`

echo text to display

`

The "echo" command allows text to be displayed while processing the command file. This is useful for displaying text to the user during processing of the command file.

`

file filename [aliasname]

`

The "file" command specifies a file to convert. When an alias is specified for argument 2, this name is used when creating the bookmark instead of the filename. If the filename or the alias name contains spaces, then they must be enclosed in quotes. If either contains a quote character, the quote character must be preceded with a backslash character. If the alias name is not specified, then a default bookmark name is used based on the filename. If the bookmark name is specified as blank (two quotes only ""), then no bookmark is generated for that file. This allows bookmarks to selectively be created for certain files in the command file.

`

info infokey infostring

`

This command adds strings to the PDF info dictionary. This dictionary contains information about the PDF file, including subject, author, and title. The keys are case sensitive. infostring should be enclosed in quotes. The command info keys are:

Subject - the subject of the PDF file

Author - the writer of the PDF file

Title - The title of the PDF file

`

param paramkey paramstring

`

The "param" command allows configuration parameters normally stored in the .ini file to be included in the command file. This allows one to create a profile from scratch or modify an existing profile by first using the "profile" command.

`

profile profilename

`

The "profile" command specifies the profile to use as defined in the INI file. The profile name must be a valid profile. This option is similar to the "-p" command line option, however, it allows for the profile to change during the processing of the command file.

### Example

`

#! txt2pdf
# example command file for DaVince Tools txt2pdf
# all comments start with ' or #
# specify PDF filename
create systemfiles.pdf
# specify profile from txt2pdf.ini
profile fixed-80x60
# convert autoexec.bat
file c:\autoexec.bat
# convert config.sys
file c:\config.sys

`