Provided by: hylafax-client_4.2.5-1_i386 bug

NAME

       typerules - HylaFAX file type identification and conversion rules

DESCRIPTION

       Only  three  types  of  files  are  accepted  by the HylaFAX server for
       transmission as facsimile: POSTSCRIPT® files, PDF files, and 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 /etc/hylafax/typerules, an ASCII  file  that  is  patterned
       after  the  /etc/magic  file  used  by  the  System  V file(1) program.
       However, there are significant differences, noted below.

       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,  primary  rules  and  secondary  rules.
       Secondary  rules specify additional rules to apply 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.

       Each rule consists of a set of whitespace-separated fields:
            offset    datatype    match    result   command
       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.

       The fields in each rule entry are:

       offset    The byte offset in the file at which data should be extracted
                 and compared to a matching string or value.

       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),   or
                 ‘‘ascii’’ (an array of ASCII-only bytes).

       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 match anything; otherwise the following
                 operators are supported (where data is  the  value  extracted
                 from  the  file  and  value  is specified in the match field)
                 except for types ‘‘string’’ and ‘‘ascii’’:
                 =     data == value              !=    data != value
                 >     data > value               <     data < value
                 <=    data <= value              >=    data >= value
                 &     (data & value) == value    !     (data & value) != value
                 ^     (data ^ value) != 0

       If no operation is specified then ‘‘=’’ is used.

       For ‘‘string’’ 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.

       result    One of ‘‘ps’’, ‘‘tiff’’,  or  ‘‘error’’  (case  insensitive).
                 The  first  two  results specify whether the rule generates a
                 POSTSCRIPT file or a 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
                 command field used in an error message.

       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:
                 %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 directry where HylaFAX filter programs reside
                 %<x>    the <x> character (e.g. ‘‘%%’’ results in ‘‘%’’
       See below for example uses of these codes.

EXAMPLES

       The following rules are used to match  the  formats  that  are  handled
       directly by the server:
       #offset   datatype    match          result    command
       0         string      %!             ps                       # POSTSCRIPT
       0         string      %PDF           ps                       # POSTSCRIPT by Ghostscript
       0         short       0x4d4d         tiff                     # big-endian TIFF
       0         short       0x4949         tiff                     # little-endian TIFF

       These  rules  are  used  to  process the ASCII version of IRIS Inventor
       database files while blocking the transmission  of  the  binary  format
       variant:
       #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\
                                                          -U -q >%o <%i

       This  rule  is  typically  the  last  entry  in the file and is used to
       convert all unmatched ASCII data files to POSTSCRIPT:
       #offset   datatype    match          result    command
       0         ascii       x              ps        %F/textfmt -fCourier-Bold -p11bp -U -q >%o <%i

NOTES

       It is much better  to  convert  data  that  is  to  be  transmitted  to
       POSTSCRIPT  because this data format permits the facsimile server to do
       the  final  imaging  according  to  the  optimal  transfer   parameters
       (resolution, binary encoding, etc.).

       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.

SEE ALSO

       sendfax(1), hylafax-client(1)

                                 May 12, 1993                     TYPERULES(5)