Version: 2.1
Part of DaVince Tools
Last Modified: September 25, 2002
Refer to the "DaVince Tools" Converters page for a description of the command line syntax for all converters.
"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:
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 space character |
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 |
Refer to the "DaVince Tools" Converters page for a description of the common profile 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
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) |
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. |
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):
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). |
(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 -" |
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. |
|
Bool |
When true, create "green bars" on the page to give it a legacy report look. The default is false. |
||
Multiple options |
Define various options for the bar wizard |
||
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. |
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 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 |
&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 |
The default header and footer string is "|- &p -". This places a page number in the center of the page.
Copying text to the
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.
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
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 purchase 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) |
Color |
The color of the green bar (it does not have to be green). Must be set to either "green", "blue" or "gray". The default is "green" |
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) |
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,color:green,lineskip:0,linenumbers:true
The wizard utilizes the page size and its margins in determining the geometry of the bars itself.
A list of new features and changes, along with a version history, can be found in the release notes.
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.
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.