asciitiff - Convert an ASCII file into a TIFF image

SYNOPSIS
asciitiff [ options ] file1 file2...

DESCRIPTION
Asciitiff converts an ASCII file into a raster image stored in a TIFF file. In addition to supporting a number of options, asciitiff also handles a number of imbedded commands that affect its operation.

Asciitiff is used by Faximum to format the cover sheets.

If the -o option is not used to name an output file, the output file is named by taking the input file name and adding .tif. If the file name already ends in a "." extension, then it is replaced with .tif.

No input file or a file with the name `-' implies standard input.

OPTIONS

-a: Appends to an existing TIFF file (otherwise, overwrites existing file). The file is created if it does not already exist.
-d: Produces debugging output describing the internal operation of asciitiff.
-D name=value: Sets the value of the named variable to the specified value (see the define and replace commands below).
-f font: Uses the named font as the current font. For more information, see Cover Sheet Fonts.
-I dir: Adds dir to the list of directories searched when including a TIFF file (see the tiffinclude and tiffoverlay commands below).
-h: Produces high (fine) resolution output (204 d.p.i. horizontally and 196 d.p.i. vertically). This is the default.
-i indent: Sets the indentation on the left-hand side of the page. The value may be suffixed by i to indicate inches (the default), c for centimeters, or p for pixels.
-l: Produces low (standard) resolution output (204 d.p.i. horizontally and 98 d.p.i. vertically).
-o file: Uses the named file as the TIFF output file.
-O overlay-file: Uses the named file (which must be a TIFF image in either standard or fine resolution) as the letterhead overlay. If the overlay file contains only one TIFF image, this image is overlayed only on the first page rendered by asciitiff. If the overlay file contains more than one TIFF image, the first image is overlayed on the first page rendered by asciitiff, and the second overlay file image is overlayed on every subsequent page rendered by asciitiff.
-P page-number: Changes asciitiff's idea of the current page number thus affecting which page of the overlay-file is used. For example, asciitiff -O ovfile -P 2 ... causes asciitiff to overlay the second page of ovfile on every page rendered by asciitiff. This option makes sense only when used with the -O option and with a multi-page overlay file.
-q: Runs quietly (without producing messages indicating the progress and number of pages converted).
-s size: Sets the size of the page to be created. The value may be suffixed by i to indicate inches (the default), c for centimeters, or p for pixels.
-t: Trims trailing whitespace from the bottom of each page.

COMMANDS
asciitiff recognises input of the form $[command arguments] as a command to asciitiff. In any of the following commands where a position expression (i.e. centre-x) is required, you may use an expression. Expressions may use any of the standard arithmetic operators (*, `/', `+', or `-') as well as parentheses.

.: Represents the current position.
$: Represents the maximum possible value.
@: Represents the position last remembered using the mark command (see below).

Constants may be followed by i to indicate inches, p to indicate pixels, or c to indicate centimetres.

By default, the horizontal unit is in units of a character width, and the vertical unit is in units of (character) lines. The upper left corner is (0,0). The x axis (the first number of the pair) is the horizontal position across the line. The y axis (the second number of the pair) is the vertical position down the page.

NOTE: Decimal numbers must start with a digit (i.e. 0.5 rather than just .5).

The following lists the commands and their actions.

arc centre-x centre-y start-x start-y end-x end-y
Draws an arc with its centre at (centre-x, centre-y) starting at (start-x, start-y) and continuing until it reaches a line drawn from (centre-x, centre-y) to (end-x, end-y).

box start-x start-y end-x end-y [radius]
Draws a box with the upper left corner at (start-x, start-y) and the lower right corner at (end-x, end-y). If the optional fifth parameter radius has been supplied, then the box is drawn with rounded corners of the specified radius.

circle centre-x centre-y radius
Draws a circle with a radius of radius and a centre at (centre-x, centre-y).

cut [page-length]
Ends the current page at position page-length or if no argument, at the current position.

date format-string
Inserts the date and time at the current position. The format-string may contain any of the time format specifiers supported by the strftime `C' library routine. See the manual page on strftime in this appendix for details on the format specifiers. If format-string is omitted, the default specifier %c is used.

define variable value
Sets the value of variable to value. The value of a named variable may be accessed using the replace command (see below).

font fontname
Changes the current font to the specified font. For more information, see Cover Sheet Fonts.

ifdef arg1 arg2
Conditionally includes arg2 at the current position if arg1 is defined.

ifndef arg1 arg2
Conditionally includes arg2 at the current position if arg1 is not defined.

include filename
Includes the contents of the specified (text) file.

line start-x start-y end-x end-y
Draws a line from (start-x, start-y) to (end-x, end-y).

moveto x y
Moves the current point to the specified location.

replace variable [default-value]
Substitutes the value of the names variable. If the variable has not been defined, then use the default value specified. The second parameter (the default value) need not be specified.

need distance
Ensures that there is at least distance space available. If the distance between the current position and the end of the page is less that distance, the current position is moved to the top of the next page. The value may be suffixed by i to indicate inches (the default), c for centimeters, or p for pixels.

set parameter
Sets a system parameter. System parameters include:

line-width: which specifies how wide lines are to be drawn (for arc, circle, box, and line commands);
indent: which specifies the size of the left margin so that characters are not placed too close to the edge of the page (note that the ITU-T recommendation indicates that characters closer than 9.2mm (0.362in) to the edge of the page may not be printed by the receiving FAX);
first-page-bottom-margin: which specifies the bottom margin on the first page (which is useful when creating cover sheets that incorporate letterhead that has printing on the bottom of the page).

set-mark x y
Sets the current mark (remembered position) to the coordinates specified (usually `.' or the current location). The x or y component of the remembered position may be referenced by using the @ character in place of either the x or y parameter. For example, to return to the marked position, use $[moveto @ @].

shell command
Executes the shell command and inserts the resulting output at the current position.

tiffinclude filename [ [ [ [start-x] start-y] end-x] end-y]
tiffoverlay filename [ [ [ [start-x] start-y] end-x] end-y]
Includes the specified TIFF image at the specified location. Note that the difference between tiffinclude and tiffoverlay is that in the case of tiffinclude, the image being included is considered to be opaque and obscures any underlying image while with tiffoverlay, the image being overlaid is considered to be transparent and any underlying image will show through. If either of the starting positions is omitted, then 0 is assumed. If either of the ending positions is omitted, then $ is assumed.

Asciitiff also recognises the following special characters in the input stream and processes them appropriately: formfeed; tab; backspace; newline; carriage return; reverse linefeed (ESC 7); reverse half-linefeed (ESC 8); and forward half-linefeed (ESC 9).

FILES
/opt/FAXserver/coversheet/* (coversheet definition files)