Provided by: hylafax-server_6.0.4-10ubuntu1_i386 bug

NAME

       dialrules - HylaFAX dial string processing rules

DESCRIPTION

       A  dial  string specifies how to dial the telephone in order to reach a
       destination facsimile machine,  or  similar  device.   This  string  is
       supplied  by  a  user  with each outgoing facsimile job.  User-supplied
       dial strings need to be processed in two ways  by  the  HylaFAX  server
       processes:  to  craft  a canonical phone number for use in locating the
       receiver's capabilities, and  to  process  into  a  form  suitable  for
       sending  to  a  modem.   In  addition  client  applications may need to
       process a dial string to formulate  an  external  form  that  does  not
       include  private  information such as a credit card access code.  Phone
       number canonicalization and dial string preparation are done  according
       to dial string processing rules that are located in a file specified in
       the server configuration file; see  the  DialStringRules  parameter  in
       hylafax-config(5).   The  generation of an externalized form for a dial
       string   is   done    by    rules    that    optionally    appear    in
       /etc/hylafax/dialrules on client machines.

       A  dial  string rules file is an ASCII file containing one or more rule
       sets.  A rule set defines  a  set  of  transformation  rules  that  are
       sequentially  applied  to  a  dial string.  Each rule set is associated
       with an identifier, with certain well-known identifiers being  used  by
       the  facsimile  server or client application.  Each transformation rule
       is  a  regular  expression  and  a  replacement  string;  the   regular
       expression  is  repeatedly  applied  to  a dial string and any matching
       substring is replaced by the replacement string.

       The syntax of a dial string rules file is  as  follows.   Comments  are
       introduced  with  the  ``!''  character  and continue to the end of the
       current line.  Identifiers are formed from a leading alphabetic and any
       number  of  subsequent  alpha-numeric characters.  A rule set is of the
       form:
              Identifier := [
                  rule1
                  rule2
                  ...
              ]
       where rule1, rule2, and so on are transformation  rules.   Line  breaks
       are significant.  The initial rule set definition line and the trailing
       ``]'' must be on separate lines; and each transformation rule must also
       be on a single line.  Transformation rules are of the form:
            regular-expression = replacement
       where  regular-expression is a POSIX 1003.2 extended regular expression
       and replacement is a string that is substituted in place of any portion
       of  the  dial  string that is matched by the regular-expression.  White
       space is significant in parsing transformation  rules.   If  a  regular
       expression  or  replacement string has embedded white space in it, then
       the white space needs to be escaped  with  a  ``\''  character  or  the
       entire  string  should be enclosed in quote (``"'') marks.  Replacement
       strings  may  reference  the  entire  string  matched  by  the  regular
       expression  with  the  ``&''  character.   Substrings  matched with the
       ``(...)'' constructs may be referenced by using ``\n''  where  n  is  a
       single  numeric  digit  between 1 and 9 that refers to the n-th matched
       substring; c.f.  re_format(7), sed(1), etc.

       To simplify and parameterize the construction of rule sets, dial string
       rules files may also include simple text-oriented variable definitions.
       A line of the form:
            foo=string
       defines a variable named foo that has the value string.  String  values
       with embedded whitespace must use the ``\'' character or be enclosed in
       quote marks.  Variables are interpolated into transformation  rules  by
       referencing them as:
            ${var}
       Note  that  variable  interpolation  is  done  only once, at the time a
       transformation rule is defined.  This means that forward references are
       not  supported and that circular definitions will not cause loops.  The
       facsimile server automatically  defines  four  variables  to  have  the
       values  defined  in  its  configuration  file:  AreaCode,  CountryCode,
       LongDistancePrefix,  and  InternationalPrefix   These   variables   are
       initialized  before  parsing a dial string rules file; thus if they are
       defined in the rules file then they will override any definition by the
       server.

       There are three well known rule set names: CanonicalNumber to convert a
       dial string to a canonical format, DialString to prepare a dial  string
       before  using  it to dial the telephone, and DisplayNumber to convert a
       dial string to an external ``displayable'' form that does  not  include
       the private information that might appear in the raw dial string.

EXAMPLES

       This  is the default set of rules for transforming a dial string into a
       canonical phone number:
              Area=${AreaCode}                  ! local area code
              Country=${CountryCode}            ! local country code
              IDPrefix=${InternationalPrefix}   ! prefix for placing an international call
              LDPrefix=${LongDistancePrefix}    ! prefix for placing a long distance call
              !
              ! Convert a phone number to a canonical format:
              !
              !    +<country><areacode><rest>
              !
              ! by (possibly) stripping off leading dialing prefixes for
              ! long distance and/or international dialing.
              !
              CanonicalNumber := [
              %.*               =                          ! strip calling card stuff
              [abcABC]          = 2                        ! these convert alpha to numbers
              [defDEF]          = 3
              [ghiGHI]          = 4
              [jklJKL]          = 5
              [mnoMNO]          = 6
              [prsPRS]          = 7
              [tuvTUV]          = 8
              [wxyWXY]          = 9
              [^+0-9]+          =                          ! strip white space etc.
              ^${IDPrefix}      = +                        ! replace int. dialing code
              ^${LDPrefix}      = +${Country}              ! replace l.d. dialing code
              ^[^+]             = +${Country}${Area}&      ! otherwise, insert canon form
              ]
       The first rule simply strips anything  following  a  ``%'';  this  will
       remove  any  calling  card-related  information.   The next eight rules
       convert upper and lower case alphabetics to the equivalent key  numbers
       (this  is  convenient  for users that use mnemonic phone numbers).  The
       tenth rule removes everything but numbers and plus signs.  The eleventh
       rule  translates  any  explicit  international  dialing prefix into the
       ``+'' symbol used to identify country codes.  The twelfth rule replaces
       a  leading  long  distance  dialing  prefix with the local country code
       string.  The last rule matches local  phone  numbers  and  inserts  the
       local country code and area code.

       As an example, assume that
              AreaCode=415
              CountryCode=1
              InternationalPrefix=011
              LongDistancePrefix=1
       then  if  the  above set of rules is applied to ``01123965-Tube%2345'',
       the transformations would be:
              01123965-Tube%2345    01123965-Tube    ! strip calling card stuff
              01123965-Tube         01123965-8823    ! convert alphabetics
              01123965-8823         011239658823     ! strip white space etc.
              011239658823          +239658823       ! replace int. dialing code
              +239658823            +239658823       ! replace l.d. dialing code
              +239658823            +239658823       ! otherwise, insert canon form
       for a final result of ``+239658823''.

SEE ALSO

       sendfax(1), dialtest(8),  faxq(8),  faxsend(8),  faxgetty(8),  hylafax-
       config(5)

                                  May 8, 1996                     DIALRULES(5)