Defoma::Subst(t)                                 Defoma::Subst(t)



NAME
       Defoma::Subst  - Defoma module to handle Subst cache/rule.

SYNOPSIS
       use Defoma::Subst;

       $Sb = defoma_subst_open(
         rulename => rulename,
         threshold => threshold,
         idobject => id_object,
         private => private_flag );

       defoma_subst_close( subst_object );

       defoma_subst_register( subst_object, font, realname );

       defoma_subst_unregister( subst_object, font realname );

       defoma_subst_add_rule( subst_object, required_id,  rule...
       );

       defoma_subst_remove_rule(    subst_object,    required_id,
       rule...  );


DESCRIPTION
       Defoma::Subst is a Defoma module to handle subst-cache and
       subst-rule.  When a certain id is required but not provid-
       ed as RealName or Alias by any font, fonts which have sim-
       ilar  appearance and the same characters should substitute
       for such a font. Required ids and their information  about
       appearance  and  charset  things  (called  *rule*) are de-
       scribed in a subst-rule.  Defoma::Subst  compares  such  a
       rule of a certain required id with hints of a substitutive
       font and calculates the degree of similarity  in  percent-
       age,  and  registers the required id and the font with the
       value as its priority as 'Substituted' type to an id-cache
       through Defoma::Id module.

       subst-rule is mainly edittable by users, which means users
       edit subst-rule file to add/remove/modify the required ids
       and  their  information, but sometimes unedittable by them
       and modified by a Defoma-configuration script.  The former
       is  called public subst-rule and the latter is called pri-
       vate subst-rule.

       subst-cache holds fonts which are candidacies for  substi-
       tuting  for  required ids. As mentioned above, a rule of a
       required id and hints of such a font are  compared.  Hints
       are  not  recorded  in  a subst-cache so retrieved from an
       id-cache. In addition a  required  id  and  its  rule  are
       recorded  in an subst-rule, so subst-cache, subst-rule and
       id-cache are strongly linked  up.  Especially  subst-cache
       and  subst-rule are not separatable and Defoma::Subst han-
       dles these two through a single united object.

       defoma_subst_open is a function used to open a subst-cache
       and  subst-rule specified by rulename and private_flag and
       returns the subst_object used for further  operation.   If
       the subst-rule is private one, set private_flag to non-ze-
       ro. Otherwise it can be omitted.  The  subst-rule  becomes
       public.   id_object  must be specified because subst-cache
       and subst-rule are strongly linked up to id-cache as  men-
       tioned  above.  Hints of a substitutive font are retrieved
       from the id-cache specified by the id_object, and required
       ids  described  in  the  subst-rule  are registered to the
       id-cache.  threshold prevents fonts that have less  degree
       of  similarity from being registered.  If a required id is
       already registered in  the  id-cache,  substitutive  fonts
       whose  degree  of  similarity are less than this threshold
       are not registered to an id-cache.

       defoma_subst_close is a function  used  to  close  a  sub-
       st-cache and subst-rule specified by subst_object.  Inter-
       nally it writes the content of cache and rule stored in  a
       memory to files.

       defoma_subst_register  is  a  function  used to register a
       font which is candidate for substituting for required  ids
       to the subst-cache specified by subst_object.  RealName of
       the font must be specified.

       defoma_subst_unregister is a function used to unregister a
       font  from the subst-cache specified by subst_object.  Re-
       alName can be omitted.

       defoma_subst_add_rule is a function used to add a required
       id  and  its rule to the subst-rule specified by subst_ob-
       ject.

       defoma_subst_remove_rule is a function used  to  remove  a
       required  id and its rule from the subst-rule specified by
       sbst_object.  If rule is omitted, all the rules describing
       the required_id are removed from the subst-rule. Otherwise
       only one rule specified by rule  and  required_id  is  re-
       moved.

EXAMPLES
       1. Open private subst-rule and subst-rule.

       $Id = defoma_id_open();
       $Sb = defoma_subst_open(rulename => 'subst1',
                               idobject => $Id);

       2. Register a substitutive font.

       defoma_id_register($Id, type => 'real',
                          font => $font,
                          id => $realname,
                          priority => $priority,
                          hints => join(' ', @_));
       defoma_subst_register($Sb, $font, $realname);

       3. Unregister.

       defoma_subst_unregister($Id, $font);
       defoma_id_unregister($Id, 'real', $font);

       4. Add a rule.

       defoma_subst_add_rule($Sb, 'Helvetica', @hints);

       5. Remove all rules for Helvetica.

       defoma_subst_remove_rule($Sb, 'Helvetica');


SEE ALSO
       defoma(a).  Defoma::Id(d).




                          March  4, 2001         Defoma::Subst(t)