TYPERULES(5F)                                       TYPERULES(5F)



NAME
       typerules  -  HylaFAX file type identification and conver-
       sion 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 two 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 trans-
       mission.    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.

       Type rules work by matching data patterns in a file; typi-
       cally 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  spec-
       ify  additional  rules  to  apply after a primary rule has
       been matched.  When secondary rules are used,  rule  scan-
       ning  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.  Com-
       ments 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 speci-
                 fied 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 opera-
                 tors are supported  (where  data  is  the  value
                 extracted  from  the file and value is specified
                 in the match field):
                 =     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.

       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  fac-
                 simile).   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 mm
                 %W      page width in pixels
                 %l      page length in mm
                 %L      page length in pixels
                 %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  transmit-
       ted  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(5F)