txt2pdf – Convert Text Files to PDF

Version: 3.0

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

Last Modified: July 8, 2004

Command Syntax

Description

New Features / Changes

Additional Information

About DaVince Tools

Command Syntax:

Refer to the "DaVince Tools" Converters page for a description of the command line syntax for all converters.

Description:

"txt2pdf" is a command line program that converts ASCII text files to PDF (Portable Document Format) files (for a Windows interface to this program, see wdavince). The key features of this program are:

Choice of any of the base 14 fonts
Support for 3 standard font encoding types for use with international characters
Text re-flow support with left or full justification
Support for legacy carriage control used in FORTRAN and COBOL generated reports
Automatic detection of DOS, Unix and Mac text files
PDF file compression support
Web optimization support
Multiple column support
Article thread option
Optional "green bar" background
Automatic bookmark creation option
Customizable headers and footers
Header, footer and column line option
Convert many text files to one PDF, a directory of text files to one PDF, or create a PDF file for each text file
Individual filenames with wildcard support and/or an entire directory may be specified for conversion
Specify files or directories to convert either via the command line or a command file
Large file support (1,000+ pages)
Creates a version 1.2 PDF file with a unique file ID in trailer

The application reads text files independent of the end of line character sequence. This allows DOS, Unix and Mac text files to be read by the application. The screen output can be redirected to a file adding the DOS syntax ">filename" to the end of the command line. This can be used to redirect output to a log file. The program returns an error code of 1 when a fatal error occurs, used in batch programs to test the success of the program.

Special characters provide additional functionality during conversion. They are listed below:

Character Behavior in Application

Horizontal Tab (HT) Replace tab character with 1 or more spaces (see "TabSpace" parameter)

Form Feed (FF) Skip to next page

Vertical Tab (VT) Skip to next column. If at the last column in the page, or the page contains only 1 column, skip to next page

Other characters in column position 1 provide additional carriage control features when "legacy" mode is enabled (see below for additional information).

The initialization file and the use of profiles is described in the "DaVince Tools" Converters page. In addition to the default profile, the following sample profiles are defined in the txt2pdf.ini file that ships with the program:

Profile Name Description

fixed-80x60 Fixed font, 80 characters per line, 60 lines per page, portrait mode, line wrap at margin. Useful for printing standard text files in a fixed font that assumes 80 characters per line.

fixedbar-80x60 Same as "fixed-80x60" with a green bar background.

legacy-80x60 Fixed font, 80 characters per line, 60 lines per page, portrait mode, line wrap at margin. Same as "fixed-80x60", except it uses the legacy carriage control characters in column 1 (i.e "1" is form feed, "0" is double space).

legacybar-80x60 Same as "legacy-80x60" with a green bar background.

fixed-132x60 Fixed font, 132 characters per line, 60 lines per page, landscape mode, line wrap at margin. Useful for printing standard text files in a fixed font that assumes 132 characters per line.

fixedbar-132x60 Same as "Fixed-132x60" with a green bar background.

legacy-132x60 Fixed font, 132 characters per line, 60 lines per page, landscape mode, line wrap at margin. Same as "Fixed-132x60", except it uses the legacy carriage control characters in column 1 (i.e "1" is form feed, "0" is double space).

legacybar-132x60 Same as "Legacy-132x60" with a green bar background

book-1col Proportional font, 12 point font, word wrap with text reflow, 1 column, page numbers

book-2col Proportional font, 12 point font, word wrap with text reflow, 2 columns, page numbers

Common Profile Settings

Refer to the "DaVince Tools" Converters page for a description of the common profile settings.

Converter Specific Settings

These tables describe txt2pdf.ini settings that are unique to this converter. They are divided into the following categories:

Margin and Layout INI Options
Font INI Options
Header and Footer INI Options
Misc. INI Options

Margin and Layout INI Options

Option	Data Type	Description
Leftmargin	Number (in points)	The left margin. The default is 36 points (.5 inches)
Rightmargin	Number (in points)	The right margin. The default is 36 points (.5 inches)
Topmargin	Number (in points)	The top margin. The default is 36 points (.5 inches)
Bottommargin	Number (in points)	The bottom margin. The default is 36 points (.5 inches)
Columnmargin	Number (in points)	The margin between columns if number of columns is greater than 1. The default is 14.4 points (.2 inches)
Columns	Number	Number of columns per page (default is 1)
Duplex	Bool	The margins, header and footer text are adjusted to conform to duplex printing when this is enabled. The default value is false.
Paper	Letter \| legal \| executive \| ledger \| a0 \| a1 \| a2 \| a3 \| a4 \| a5 \| a6 \| a7 \| a8 \| a9 \| a10 \| custom w h	The paper size. The default is letter. For a custom paper size, w and h are the width and height of the custom paper size, respectively.
Orientation	Portrait \| landscape	The paper orientation. The default is portrait.

Font INI Options

Option	Data Type	Description
Leading	Number + "" \| "x" \| "lpi"	Leading is the vertical spacing between lines. It can be specified 3 ways. A number by itself specifies the leading as a point size. Specifying a leading value less than your font size can result in overlapping text. A number with "x" specifies the factor to apply against the font size to determine the leading value. For example, "1x" refers to a leading value equal to the font size value. A value of "2x" refers to a leading value equal to twice the font size value (double space). A number with "lpi" specifies the leading as a "lines per inch" value. Default is 1x.
Font	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 Courier). An optional encoding can be specified. The encoding name is also case sensitive (default encoding is Default).
Fontsize	Number (in points)	The size of the font, in points (there are 72 points in 1 inch). The default value is 12 points.
Wrapmode	truncate \| margin \| legacy \| word	Method of wrapping lines (lines longer than the column width). Choices are: Truncate – do not show anything past margin Margin (default) – wrap line at margin to next line Legacy - use column 1 for carriage control in the following manner (used in COBOL and FORTRAN formatted output): '1' - form feed blank - single space '0' - double space '-' - triple space Word – wrap line at word to next line
Justification	Left \| full	When wrap mode is set to "word" and justification is set to "full", perform full justification, which removes the ragged text edge on the right margin (default is left).

Header and Footer INI Options

(more information is also in the "Headers and Footers" section below)

Option	Data Type	Description
Header	Bool	Display header on each page. Default is false.
Headerfont	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 used in the header. 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 Courier). An optional encoding can be specified. The encoding name is also case sensitive (default encoding is Default).
Headerfontsize	Number (in points)	The size of the font used in the header, in points (there are 72 points in 1 inch). The default is 12 points.
Headerstring	String	Customized header string (see below for syntax). Default is "\|- &p -"
Footer	Bool	Display footer on each page. Default is false.
Footerfont	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 used in the footer. 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 Courier). An optional encoding can be specified. The encoding name is also case sensitive (default encoding is Default).
Footerfontsize	Number (in points)	The size of the font used in the footer, in points (there are 72 points in 1 inch). The default is 12 points.
Headerlinewidth	Number (in points)	Draws a horizontal line of the specified width between the header and the top of the text on a page. This value should be set to less than the value of the Fontsize tag. Set to zero when no line is desired (default value is zero).
Footerlinewidth	Number (in points)	Draws a horizontal line of the specified width between the footer and the bottom of the text on a page. This value should be set to less than the value of the Fontsize tag. Set to zero when no line is desired (default value is zero).
Columnlinewidth	Number (in points)	If Columns is set to 2 or more, this option draws a vertical line at the specified width between the columns. This value should be set to less than the value of the Columnmargin tag. Set to zero when no line is desired (default value is zero).
Footerstring	String	Customized footer string (see below for syntax). Default is "\|- &p -"

Misc. INI Settings

OptionDescription
PageTrim	Front \| back \| both \| none	Remove blank pages from either the front or back of the resulting PDF file, or both. Blank pages result when extra form feed characters appear at the beginning or end of the text stream. The default is none.
Articles	Bool	Create article threads for document. When combining multiple text files into 1 PDF file, an article thread is created for each file. The default is false.
ArticleMargin*	Number	Margin to use in points when zoomed in to an article. This option adds white space around the article text. The default is 0
BarWizard	Bool	When true, create "green bars" on the page to give it a legacy report look. The default is false.
BarWizardOptions *	Multiple options	Define various options for the bar wizard (see below)
ForcePage *	none \| odd \| even	Forces first page to an odd or even page if "odd" or "even" specified, respectively. Otherwise, print first page on the very next page. This option can create blank pages when converting multiple files to a single PDF file. Default is "none".
ParagraphWizard	Bool	When used with "wrapmode=word", this wizard removes linefeeds at the end of a line if the next lines does not contain a space or blank line. The effect of this is that the resulting PDF file will have a better text flow at the margin. The default is false.
ResetPageNumber	Bool	If combining multiple text files into a single PDF file, reset the page number to "1" between each file. This is useful if you are printing the page number in the header or footer. The default is false.
TabSpace	Integer	Convert tabs to this specified number of spaces. The default is "8".
WebLink*	Bool	Will create a web link for any text begining with "www", "http://", "https://", "ftp://", "ldap://" or "mailto:". The default is false.
WebLinkLineWidth*	Number	Width of underline in points when weblinks are used. The default is 1 point

* New or changed in version 3

All margin, leading, line and font size parameters are specified in "points". A point is a unit of measurement equal to 1/72 of an inch. A 1/2 inch margin would be specified as 36 points. A 12 point font with 1x leading specified would print at 72/12 or 6 lines per inch.

Headers and Footers

Headers and footers are customizable. The single line of text can be left, centered and right justified using the vertical pipe character "|" as a tab character. Text is initially left justified. After the first "|" character, the following text is centered. Another "|" character will right justify text following the second tab. Variables can be specified to be a part of the text in the header or footer. A variable starts with the ampersand character "&", followed by a single character. Variables are case sensitive. The following variables are available for use in a header or footer:

&&	Literal ampersand character "&"
&a	Author name as specified on the command line
&A	Alias of file being processed (via command file), or name of file if no alias specified
&d	Date of file
&D	Current system date
&f	Name of file being processed
&p	Current page number
&r *	Current page number in roman numerals (lowercase)
&R *	Current page number in roman numerals (uppercase)
&s	Subject name as specified on the command line
&t	Time of file
&T	Current system time
&w	Title or file name if title not present on command line

* New in version 3

The default header and footer string is "|- &p -". This places a page number in the center of the page.

Copying Text to the Clipboard

To copy text to the clipboard from a multi-column PDF file, use the text selection tool and press the CTRL key while dragging a rectangle around the area. You can only copy 1 column of text at a time using this method.

Determining Characters per Line and Lines Per Page

There is no direct way of specifying the number of characters per line when using a fixed font. The number of characters per line is dependent on the width of the page, the number of columns, the margins and the size of the font. The following formula can be used to set the text font point size when a specific number of characters per line is required:

(text font size) = ((page width)- (left margin) - (right margin) - ((# of columns) -1) * (column margin)) / (chars per line) / 0.6

(text font size, page width, and margins must be specified in points)

For example:

Page Width 612 points (8.5 inches)

Left Margin 72 points (1 inch)

Right Margin 72 points (1 inch)

# of chars per line 80

# of columns 1

(text font size) = ((612 - 72 - 72 - 0)/ 80 / .6 = 9.75

Therefore, a font size of 9.75 points is required to print 80 characters per line.

Similarly, the number of lines per page cannot be specified directly. However, a value for leading can be calculated to get the desired lines per page. The following formula can be used to determine the leading based on a desired number of lines per page (note that for calculation purposes, the header and footer lines each count as one line):

(total lines per page) = (lines per page)

if (header line width) > 0 then (total lines per page) = (total lines per page) + 1

if (footer line width) > 0 then (total lines per page) = (total lines per page) + 1

(absolute leading) = ((page height)- (top margin) - (bottom margin) - (header height) - (footer height)) / (total lines per page)

(font size, page height, and margins must be specified in points)

Note that overlapping text can occur if the leading value is less the font size. The header and footer heights are zero if they are disabled, otherwise, they are calculated as follows:

(header height) = (header font size)

(footer height) = (footer font size)

For example:

Page Height 792 points (11.0 inches)

Top Margin 36 points (0.5 inch)

Bottom Margin 36 points (0.5 inch)

Desired # of lines per page 60

Text Font Size 12

Header Font Size 14

Header Line Width 2

Footer Font Size disabled

Footer Line Width 0

First calculate the header height:

(header height) = (14)

(total lines per page) = 60 + 1 = 61

Footer height is zero, now calculate leading value:

(absolute leading) = ((792)- (36) - (36) - (14) - (0)) / (61) = 11.574 points

Bar Wizard Options

When the bar wizard is enabled, it creates a "green bar" background to the page. This "green bar" background is used to help ease the horizontal reading of a legacy report. This eliminates the need to use green bar paper since the green bars are a part of the PDF file.

The option "BarWizard" is used to enable or disable the green bar background. The option "BarWizardOptions" allows one to customize the layout of the green bar background. The following parameters can be used with this option:

BarHeight The height of the green bar, in points. The default is 36 points (.5 inches)

BarColor *
The color of the green bar (it does not have to be green). The color is defined as either a color name or HTML style color definition in the format #RRGGBB (#000000 = black, #FFFFFF = white, #0000FF = blue, etc.). The default is "#DFFFDF".
Note: In previous releases, this option was named "Color".

LineColor *
The color of the green bar lines. The color is defined as either a color name or HTML style color definition in the format #RRGGBB (#000000 = black, #FFFFFF = white, #0000FF = blue, etc.). The default is "#BFDFBF".

NumberColor *
The color of the green bar text. The color is defined as either a color name or HTML style color definition in the format #RRGGBB (#000000 = black, #FFFFFF = white, #0000FF = blue, etc.). The default is "#BFDFBF" (same color as the green bar lines).

LineNumbers Boolean value. If set to true, display line numbers on the left and right sides of the bars. The default is true

LineSkip The number of lines to skip before printing the first green bar at the top of the report. This allows for white space at the top of a report to allow for a heading. The default value is "0" (no line skip)

* New or changed in version 3

These parameters are listed in a comma separated list in the format of

param:value

The following statement specifies the default values for all parameters

BarWizardOptions=barheight:36,barcolor:#DFFFDF,linecolor:#BFDFBF,numbercolor:#BFDFBF,lineskip:0,linenumbers:true

The wizard utilizes the page size and its margins in determining the geometry of the bars itself. Several profiles utilizing the green bar settings have already been defined for popular report sizes.

New Features / Changes

A list of new features and changes, along with a version history, can be found in the release notes.

Additional Information:

Any tool that creates a PDF must create an intermediate file prior to writing the PDF file. The filename of this intermediate file begins with "tmps" and appears in the directory pointed to by the environment variable "TMP". If this environment does not exist, then the temporary file is written in the current directory. The intermediate file exists only during the execution of the program.

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.

Character	Behavior in Application
Horizontal Tab (HT)	Replace tab character with 1 or more spaces (see "TabSpace" parameter)
Form Feed (FF)	Skip to next page
Vertical Tab (VT)	Skip to next column. If at the last column in the page, or the page contains only 1 column, skip to next page

Profile Name	Description
fixed-80x60	Fixed font, 80 characters per line, 60 lines per page, portrait mode, line wrap at margin. Useful for printing standard text files in a fixed font that assumes 80 characters per line.
fixedbar-80x60	Same as "fixed-80x60" with a green bar background.
legacy-80x60	Fixed font, 80 characters per line, 60 lines per page, portrait mode, line wrap at margin. Same as "fixed-80x60", except it uses the legacy carriage control characters in column 1 (i.e "1" is form feed, "0" is double space).
legacybar-80x60	Same as "legacy-80x60" with a green bar background.
fixed-132x60	Fixed font, 132 characters per line, 60 lines per page, landscape mode, line wrap at margin. Useful for printing standard text files in a fixed font that assumes 132 characters per line.
fixedbar-132x60	Same as "Fixed-132x60" with a green bar background.
legacy-132x60	Fixed font, 132 characters per line, 60 lines per page, landscape mode, line wrap at margin. Same as "Fixed-132x60", except it uses the legacy carriage control characters in column 1 (i.e "1" is form feed, "0" is double space).
legacybar-132x60	Same as "Legacy-132x60" with a green bar background
book-1col	Proportional font, 12 point font, word wrap with text reflow, 1 column, page numbers
book-2col	Proportional font, 12 point font, word wrap with text reflow, 2 columns, page numbers

Page Width	612 points (8.5 inches)
Left Margin	72 points (1 inch)
Right Margin	72 points (1 inch)
# of chars per line	80
# of columns	1

Page Height	792 points (11.0 inches)
Top Margin	36 points (0.5 inch)
Bottom Margin	36 points (0.5 inch)
Desired # of lines per page	60
Text Font Size	12
Header Font Size	14
Header Line Width	2
Footer Font Size	disabled
Footer Line Width	0

BarHeight	The height of the green bar, in points. The default is 36 points (.5 inches)
BarColor *	The color of the green bar (it does not have to be green). The color is defined as either a color name or HTML style color definition in the format #RRGGBB (#000000 = black, #FFFFFF = white, #0000FF = blue, etc.). The default is "#DFFFDF". Note: In previous releases, this option was named "Color".
LineColor *	The color of the green bar lines. The color is defined as either a color name or HTML style color definition in the format #RRGGBB (#000000 = black, #FFFFFF = white, #0000FF = blue, etc.). The default is "#BFDFBF".
NumberColor *	The color of the green bar text. The color is defined as either a color name or HTML style color definition in the format #RRGGBB (#000000 = black, #FFFFFF = white, #0000FF = blue, etc.). The default is "#BFDFBF" (same color as the green bar lines).
LineNumbers	Boolean value. If set to true, display line numbers on the left and right sides of the bars. The default is true
LineSkip	The number of lines to skip before printing the first green bar at the top of the report. This allows for white space at the top of a report to allow for a heading. The default value is "0" (no line skip)