.\"	$Id$
.\"
.\" HylaFAX Facsimile Software
.\"
.\" Copyright (c) 1993-1996 Sam Leffler
.\" Copyright (c) 1993-1996 Silicon Graphics, Inc.
.\" HylaFAX is a trademark of Silicon Graphics
.\" 
.\" Permission to use, copy, modify, distribute, and sell this software and 
.\" its documentation for any purpose is hereby granted without fee, provided
.\" that (i) the above copyright notices and this permission notice appear in
.\" all copies of the software and related documentation, and (ii) the names of
.\" Sam Leffler and Silicon Graphics may not be used in any advertising or
.\" publicity relating to the software without the specific, prior written
.\" permission of Sam Leffler and Silicon Graphics.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS-IS" AND WITHOUT WARRANTY OF ANY KIND, 
.\" EXPRESS, IMPLIED OR OTHERWISE, INCLUDING WITHOUT LIMITATION, ANY 
.\" WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.  
.\" 
.\" IN NO EVENT SHALL SAM LEFFLER OR SILICON GRAPHICS BE LIABLE FOR
.\" ANY SPECIAL, INCIDENTAL, INDIRECT OR CONSEQUENTIAL DAMAGES OF ANY KIND,
.\" OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
.\" WHETHER OR NOT ADVISED OF THE POSSIBILITY OF DAMAGE, AND ON ANY THEORY OF 
.\" LIABILITY, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE 
.\" OF THIS SOFTWARE.
.\"
.if n .po 0
.ds Fx \fIHyla\s-1FAX\s+1\fP
.ds Ps P\s-2OST\s+2S\s-2CRIPT\s+2
.TH TYPERULES 5 "May 12, 1993"
.SH NAME
typerules \- \*(Fx file type identification and conversion rules
.SH DESCRIPTION
Only three types of files are accepted by the \*(Fx
server for transmission as facsimile:
\*(Ps\(rg files, PDF files, and 
.SM TIFF
Class F (bilevel Group 3-encoded) files.
All other types of files must be converted to one
of these three formats.
The facsimile submission program
applies a set of rules against the contents
of each input file to identify the file's
type and to figure out how to convert the file to a format that is
suitable for transmission.
These rules are stored in the file
.BR /etc/hylafax/typerules ,
an
.SM ASCII
file that is patterned after the
.B /etc/magic
file used by the System V
.IR file (1)
program.  However, there are significant differences, noted below.
.PP
Type rules work by matching data patterns in a file; typically
patterns that appear in the first few bytes of the file (i.e.
magic numbers).
There are two types of rules,
.I "primary rules"
and
.IR "secondary rules" .
Secondary rules specify additional rules to apply
.I after
a primary rule has been matched.
When secondary rules are used, rule scanning
continues up to the next primary type rule in the file.
.PP
Each rule consists of a set of whitespace-separated fields:
.nf
.sp .5
.ti +.5i
.ta \w'\fIoffset\fP    'u +\w'\fIdatatype\fP    'u +\w'\fImatch\fP    'u +\w'\fIcommand\fP  'u
\fIoffset\fP	\fIdatatype\fP	\fImatch\fP	\fIresult\fP	\fIcommand\fP
.sp .5
.fi
If an line is terminated wth a backslash character, the entry
is continued on the next line with any leading whitespace characters
compressed to a single space.
Comments are marked with the ``#'' character; everything from to the
end of the line is discarded.
Secondary rules have a ``>'' character in the first column of the line;
primary rules do not.
.PP
The fields in each rule entry are:
.TP 10
.B offset
The byte offset in the file at which data should be extracted
and compared to a matching string or value.
.TP 10
.B datatype
The type of data value to extract at the specified offset for
comparison purposes; one of:
``byte''
(8 bit unsigned number),
``short''
(16 bit unsigned number),
``long''
(32 bit unsigned number),
``string''
(an array of bytes),
``istring''
(a case-insensitive array of bytes), or
``ascii''
(an array of \s-1ASCII\s+1-only bytes).
.TP 10
.B match
The value and operation to use in matching; the value used is
based on the datatype field.
If value is ``x'', then
it is interpreted to mean 
.IR "match anything" ;
otherwise the
following operators are supported (where
.I data
is the value extracted from the file and
.I value
is specified in the match field) except for types ``string'', ``istring'', and ``ascii'':
.nf
.sp .5
.RS
.ta \w'>=    'u +\w'(data & value) == value    'u +\w'>=    'u
=	data == value	!=	data != value
>	data > value	<	data < value
<=	data <= value	>=	data >= value
&	(data & value) == value	!	(data & value) != value
^	(data ^ value) != 0
.RE
.sp .5

If no operation is specified then ``='' is used.
.PP

For ``string'', ``istring'', and ``ascii'' no operator is allowed; the implicit
operation is always ``=''.  In these cases, the field is terminated by
a tab or end of line, not by ``#''.  Characters in the field have
their literal value; there are no C-style character escapes.
.fi
.TP 10
.B result
One of ``ps'', ``tiff'', or ``error'' (case insensitive).
The first two results specify whether the
rule generates a \*(Ps file or a
.SM TIFF/F
file (Group 3-encoded bilevel data), respectively.
The ``error'' result indicates that a
file is unsuitable for transmission and, if supplied for transmission,
should cause the job to be aborted with the
.I command
field used in an error message.
.TP 10
.B command
A command description that is expanded and
passed to the shell to convert the input file
to the result format (suitable for sending as facsimile).
Before the string is passed to the shell, it is scanned
and the following ``%'' escape codes are substituted for:
.nf
.sp .5
.RS
.ta \w'%<x>    'u
%i	input file name
%o	output file name
%r	output horizontal resolution in pixels/mm
%R	output horizontal resolution in pixels/inch
%v	output vertical resolution in lines/mm
%V	output vertical resolution in lines/inch
%f	data format, ``1'' for 1-d encoding or ``2'' for 2-d encoding
%w	page width in pixels
%W	page width in mm
%l	page length in pixels
%L	page length in mm
%s	page size by name
%F	the directory where \*(Fx filter programs reside
%<x>	the <x> character (e.g. ``%%'' results in ``%''
.RE
.sp .5
.fi
See below for example uses of these codes.
.SH EXAMPLES
The following rules are used to match the formats
that are handled directly by the server:
.nf
.sp .5
.ta \w'offset    'u +\w'datatype    'u +\w'#Inventor V    'u +\w'result    'u +\w'command        'u
#offset	datatype	match	result	command
0	string	%!	ps		# \*(Ps
0	string	%PDF	ps		# \*(Ps by Ghostscript
0	short	0x4d4d	tiff		# big-endian \s-1TIFF\s+1
0	short	0x4949	tiff		# little-endian \s-1TIFF\s+1
.fi
.PP
These rules are used to process the
.SM ASCII
version of
.SM IRIS
Inventor database files while blocking the transmission
of the binary format variant:
.nf
.sp .5
.ta \w'offset    'u +\w'datatype    'u +\w'#Inventor V    'u +\w'result    'u +\w'command        'u
#offset	datatype	match	result	command
0	string	#Inventor V	error	IRIS Inventor file 
>15	string	binary	error	binary IRIS Inventor file
>15	string	ascii	ps	%F/textfmt \-fCourier-Bold \-p11bp\e
				    \-U \-q >%o <%i
.fi
.PP
This rule is typically the last entry in the file and is
used to convert all unmatched \s-1ASCII\s+1 data files to \*(Ps:
.nf
.sp .5
.ta \w'offset    'u +\w'datatype    'u +\w'#Inventor V    'u +\w'result    'u +\w'command        'u
#offset	datatype	match	result	command
0	ascii	x	ps	%F/textfmt \-fCourier-Bold \-p11bp \-U \-q >%o <%i
.fi
.SH NOTES
It is much better to convert data that is to be
transmitted to \*(Ps because this data format
permits the facsimile server to do the final imaging according to
the optimal transfer parameters (resolution, binary encoding, etc.).
.PP
It might be better to allow secondary rules to augment a primary
rule rather than just replace them.
This would allow, for example, command line options to be selected
based on file type.
.SH "SEE ALSO"
.IR sendfax (1),
.IR hylafax-client (1)