NAME
AVAILABILITY
ELS, PLUS, C/S, MFAX, FMS
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 embedded commands that affect its operation.
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.
Note that there are two versions of asciitiff: pkasciitiff which is designed to use bit-mapped fonts; and fsasciitiff which is designed to use fonts supplied by an X11 font server. Since the X11 font server can provide a much wider range of fonts than are provided in the bit-mapped fonts supplied with pkasciitiff, the fsasciitiff version of asciitiff is recommended for use whenever possible.
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.
The syntax of the font name must be appropriate for the version of asciitiff being used. Please see the section below on fonts.
For the pkasciitiff version the default font is fax.12.
For the fsasciitiff version the default font depends on the platform being used but it usually something like:
-*-courier-medium-r-normal-*-*-120-200-200-m-*-iso8859-1
With fsasciitiff you can determine the current default font by running:
asciitiff -d < /dev/null
and looking for the line that starts "default font is".
-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. (PLUS only)
-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(I) 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 (fax.12 by default) to the specified font. The fontname consists of the name of a font followed optionally by a decimal point and a point size. If the point size is not specified then the current point size is used. Note that the font specified (in the appropriate point size) must exist in one of the font directories (see below). Note that the list of available fonts is different for the two resolutions. In particular, some of the smaller fonts are not available when producing standard (low) resolution output.
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:
point-size which defines the default font point size to use;
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 CCITT recommendation indicates that characters closer than 6.7mm 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).
FONTS
As mentioned earlier in this manual page, there are two versions of asciitiff each with there own syntax for font names.
The pkasciitiff version finds its bit-mapped fonts in the .../font/204x196 (for the fonts used for producing high-resolution output) and in .../font/204x98 (for low-resolution output). The font directory is in the directory where the Faximum software is installed.
The pkasciitiff font names are merely the names of the files in these font directories so to obtain a list of available fonts merely list the contents of these directories. For example, cmr.20 is Computer Modern Roman (a serif font) in 20-point size.
The fsasciitiff version uses the X11 standard font naming convention called X11 Logical Font Descriptions (XLFD). An XLFD consists of thirteen components. Take, for example, the following XLFD font name:
-bitstream-prestige-medium-r-normal-*-0-0-85-85-m-*-iso8859-1
Each of these components specifies an independent aspect of a font. In order, the components are:
1 foundry name the organisation that "invented" the font
examples: bitstream, adobe
2 family name the name of the font family
example: prestige, courier, helvetica
3 weight tbe thickness of the strokes
example: bold, medium, normal
4 angle/slant tbe code for the angle of the characters (italic, oblique, roman, ...)
example: i, o, r
5 width name tbe width of the characters
example: normal, condensed
6 other style info other information on the character style
example: sans
7 pixel size tbe height of the characters in pixels
example: 20, 24
8 point size tbe height of the characters in decipoints
example: 100, 120
9 x resolution tbe number of pixels per inch horizontally
example: 75, 200 (for fax always specify 200)
10 y resolution tbe number of pixels per inch vertically
example: 75, 200 (for fax always specify 200)
11 character spacing tbe code for the character spacing (monospace, proportionally space, ...)
example: m, p
12 character width ten times the average character width in pixels
example: 90, 149
13 character set the name of the character set encoding
example: iso8859-1, jisz0208.1983-0
With some older X11 systems it was acceptable to drop components that were not of interest by merely placing two hyphens in a row, for example:
-bitstream-prestige-medium-r-normal--0-0-85-85-m-0-iso8859-1
Some newer X11 systems will not accept this syntax and so it is strongly recommended that fields for which any value will be accepted be replaced with an asterisk, for example:
-bitstream-prestige-medium-r-normal-*-0-0-85-85-m-0-iso8859-1
To obtain a list of all of the available scalable fonts on your server, sign on to the X display connected to your system and issue the following command:
xlsfonts | grep 0-0- > /tmp/fonts
If you get an "xlsfonts: not found" error you may have to look for the directory that contains this command (try /usr/bin/X11) and issue the command as follows:
/usr/bin/X11/xlsfonts | grep 0-0- > /tmp/fonts
Select one of the fonts in the /tmp/fonts list.
If your console is running the X11 server but you are connected using a remote terminal, you may be able to get xlsfonts to run remotely by defining the DISPLAY environment variable. For example:
DISPLAY=hostname:0.0
export DISPLAY
Where hostname is the network name for your system.
As an aside if you want to see the various fonts available on your system, run the xfontsel utility from your X11 display (see your system's documentation on this command for more details).
You can change the default font used by fsasciitiff either by setting an environment variable (LORES_ASCII_FONT and HIRES_ASCII_FONT) or by setting the asciitiff-lores-ascii-font and asciitiff-hires-ascii-font parameters in the /etc/faximum.conf file.
NOTE Faximum also has special versions of asciitiff to support the Japanese character sets (JIS-0201 and JIS-0208). Please contact Faximum Software for details.
FILES
.../faximum/font/204x196
high resolution font directory
.../faximum/font/204x98
low resolution font directory
SEE ALSO
convert, strftime
Faximum TechNote 171 (www.faximum.com/technotes/171)