unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (Debian-5.0)
Page:
Section:
Apropos / Subsearch:
optional field

Defoma::Id(3pm)                                                Defoma::Id(3pm)



NAME
       Defoma::Id - Defoma module to handle Id cache.

SYNOPSIS
       use Defoma::Id;

       $Id = defoma_id_open_cache( suffix, package_name );

       defoma_id_close_cache( id_object );

       defoma_id_register( id_object,
        type => type,
        font => font,
        id => id,
        priority => priority,
        category => category,
        origin => origin,
        depend => depend,
        hints => hints );

       defoma_id_unregister( id_object,
        type => type,
        font => font,
        id => id );

       @index = defoma_id_grep_cache( id_object, search-type,
        id => id,
        font => font,
        type => type,
        category => category,
        depid => depid,
        depfont => depfont );

       @hints = defoma_id_get_hints( id_object, index );

       defoma_id_set( id_object, id, font, flag );

       defoma_id_unset( id_object, id, font );


DESCRIPTION
       Defoma::Id  is  a  Defoma  module  to  handle  identifiers of fonts and
       id-caches.  It provides functions listed above which are supposed to be
       called from Defoma-configuration scripts.

       id-cache  is sort of a database and its aim is to avoid name space con-
       flict. Applications often access fonts through their identifiers, so it
       is desirable that one identifier point only one font. It is a difficult
       requirement for automatic configuration because it  can  easily  happen
       that  two  or more fonts have the same identifier. Automatic configura-
       tion scripts can hardly detect which font is the best to be  named  the
       identifier, or even such a situation occur. Defoma::Id is help for this
       problem.

       The rough flow of how Defoma::Id works is:
       1. open an id-cache at init command of a Defoma-configuration script.
       2. register identifier(s) of a font at register command of the script.
       3. Defoma::Id looks up the id-cache to check if there's any other  font
       that  has  the  same  identifier, and calls back the script to make the
       most appropriate font have the identifier, by do-install-  command  and
       do-remove- command.

TYPE OF IDENTIFIER
       It  can handle three types of identifiers: RealName, Alias, and Substi-
       tuted.

       RealName is a real name of a font and is usually taken from  the  Font-
       Name hint.  If you want to register a font to an id-cache, at least one
       RealName must be registered. You can pass the hints to options when you
       register a RealName.
       Alias  is  another  name  of a font and is usually taken from the Alias
       hint.  You have to specify the RealName of the font  with  origin  when
       you register an Alias.
       Substituted  is yet another name of a font, but unlike Alias, it is not
       taken from the hints  of  the  font,  nor  directly  registered  to  an
       id-cache  by  Defoma-configuration  scripts.  It is rather taken from a
       subst-rule, which is handled by Defoma::Subst module, and is registered
       by  the  module.   If you want a certain font to substitute for another
       id, you should register the font (and its RealName) to  a  subst-cache.
       For more detail, please refer the Defoma::Subst manpage.

DETAIL OF HOW DEFOMA::ID WORKS
       Registration  and Unregistration of ids of a font are usually performed
       on Defoma-configuration scripts at register and unregister commands re-
       spectively,  and  actual installation and removal for a certain id of a
       font must not be performed at register and unregister commands, but  at
       do-install-(real,alias,subst) and do-remove-(real,alias,subst) commands
       respectively.  Following explains how an id of a font is registered/un-
       registered to/from an id-cache.

       1.Registeration
              Defoma::Id  module records the id, font, type, priority and some
              other informations in the id-cache.

       1.2    the module seeks fonts which provides the id from the  id-cache,
              and  gets  the  most prior font of them. RealName is always more
              prior to Alias, and Alias is always more prior to Substituted.

       1.3    If no font is actually installed for the id,  the  module  calls
              back  the  script  with do-install-<type> command. If the script
              succeeds installation of the font for the id, the module records
              the id and the font as INSTALLED.

       1.4    If  another  font  is  already  INSTALLED for the id, the module
              calls back the script with do-remove-<type>  command  to  remove
              the  old  most-prior  font for the id, and removes the INSTALLED
              entry. Then the module calls back again the script  with  do-in-
              stall-<type>  command to install the new most-prior font for the
              id. If the script succeeds installation of the font for the  id,
              the module records the id and the font as INSTALLED.

       2.Unregistration
              If  the  font  is  installed for the id, Defoma::Id module calls
              back the script with do-remove-<type> command to remove the font
              for  the  id,  and  removes the INSTALLED entry. Then the module
              seeks fonts which provides the id from the id-cache. If  the  id
              is provided by other fonts, the module seeks the most-prior font
              from them, and installs it as mentioned above section 1.3.

       2.2    The module removes the entry recording the id and the font.

       These processes make only one, more appropriate font provide an certain
       id, so the name-space conflict would be avoided.

FORMAT OF ID CACHE
       id-cache  holds  eight  items for each entry: id, font, type, priority,
       category, depid, depfont and hints.

       type represents the type of the entry in a combination of some letters.
       id-cache  handles font entry and mark entry. The latter is used to have
       a certain less prior font installed for a certain id  (i.e.  marked  as
       USE),  or  to keep a certain font from being installed for a certain id
       (i.e. marked as EXCLUDE), and is supposed to be set by users and not to
       be  referred  from Defoma-configuration scripts, just for internal use.
       On the other hand, font entry holds information of a certain  id  of  a
       font and may be referred from the scripts.

       type consists of two or three letters.  The first letter represents the
       type of the entry and is either S or M (font entry or mark  entry,  re-
       spectively).  If  the  first letter is S, which means it is font entry,
       the second letter represents the type of the font and is either r, a, S
       (real,  alias  or subst respectively).  If the first letter is M, which
       means it is mark entry, the second letter represents the  type  of  the
       mark and either of  u or x (use or exclude respectively).  If the entry
       is font entry, which means the first letter is S, and the font and  the
       id of the entry is INSTALLED, there's a third letter and it is I.

       depid  and depfont represent dependency of the id of the font. The font
       never gets installed unless the depfont is  installed  for  the  depid.
       origin  and  depend arguments of defoma_id_register affect these items.
       If the id of the font doesn't depend on any other id and/or font, these
       items are set to '.'.

       hints  represents  the  hints of the id of the font. It is specified by
       hints argument of defoma_id_register.  You must use defoma_id_get_hints
       to access the value of this item.

       An  item  of  each entry of an id-cache are accessible as an element of
       id-object whose key is e_id, e_font,  e_type,  e_priority,  e_category,
       e_depid,  e_depfont.  For example, $Id->{e_font}->[3] accesses the font
       of entry #3 of id-object $Id.

       Here's an example of an id-cache.

       # e_id        e_font e_type e_priority e_category ...
       0 Helvetica   a.pfa  SrI    20         type1 ...
       1 Courier     a.pfa  Sa     20         type1 ...
       2 Times-Roman b.ttf  SrI    30         truetype ...
       3 Courier     b.ttf  SaI    30         truetype ...

       It show a.pfa has two identifiers: Helvetica for RealName  and  Courier
       for  Alias, and b.ttf has two identifiers: Times-Roman for RealName and
       Courier For Alias.
       Two fonts have the same identifier Courier,  but  this  id-cache  makes
       Courier point to b.ttf (in other words, lets b.ttf provide Courier).

FUNCTIONS
       defoma_id_open_cache  is a function used to open an id-cache. id-caches
       are independent between applications so usually a  Defoma-configuration
       script  of a certain application cannot open an id-cache of another ap-
       plication.  Each application can have more than one id-caches, and each
       of  them are distinguished by its suffix unique to the application. You
       can omit the suffix argument if the application uses only one id-cache.
       package_name  should  be  omitted  for most cases. It returns id_object
       which is used as a descriptor for further handling of the id-cache.

       defoma_id_close_cache is a function used to close an  id-cache.  Inter-
       nally it writes the content of an id-cache to the file which is identi-
       fied by id_object.

       defoma_id_register is a function used to register a font and one of its
       ids  to  an  id-cache identified by id_object.  You must at least pass
       type, font, id and priority as its arguments.  type is either  of  're-
       al',  'alias'  or 'subst', which corresponds to RealName, Alias or Sub-
       stituted mentioned above, respectively. 'subst' should be specified on-
       ly by Defoma::Subst module, so 'real' and 'alias' are possible choices.
       If 'alias' is specified as the type of a font, you must specify the Re-
       alName  of  the  font by origin.  Specifying the origin is required for
       non-RealName ids because they should not be installed unless the  Real-
       Name of the font is installed.  If 'real' is specified as the type, you
       can specify the hints of the font by hints.

       defoma_id_unregister is a function used to unregister one or all regis-
       tered  id(s)  of  a certain font from and id-cache. If id is specified,
       only the id of the specified font is  unregistered  from  the  id-cache
       specified  by  id_object.   Otherwise, all ids of the font are unregis-
       tered.

       defoma_id_grep_cache is a function that searches the id-cache specified
       by  id_object for the specified id/font/category/depid/depfont, and re-
       turns a list of indexes.  search-type is either of real, alias,  subst,
       font,  installed or mark, which narrows down the subjects of searching.
       id ,font ,type ,category ,depid and depfont  decides  the  subjects  of
       searching  more  specifically.  Not all of these, nor none of these are
       required.

       defoma_id_get_hints is a function that returns hints of  the  index  of
       the id-cache specified by id_object .  If the index of Alias or Substi-
       tuted is specified, it returns the hints of its RealName that is speci-
       fied  in  the origin argument of defoma_id_register when the Alias/Sub-
       stituted identifier was registered.

       defoma_id_set is a function used to make the specified font provide the
       specified  id,  or  to  prevent  the  specified font from providing the
       specifid id.  install or exclude may  be  given  to  the  flag.   defo-
       ma_id_unset  is  a function used to unset the set flag of the specified
       idandfont.

EXAMPLES
       # Open an id-cache with 'test' as its suffix.
       $Id = defoma_id_open_cache('test');

       # register ids in register command.
       my $font = shift;
       my $h = parse_hints_start('Alias', @_);
       my $fontname = $h->{FontName};
       my @alias = split(/ /, $h->{Alias});
       my $pri = $h->{Priority};

       defoma_id_register($Id,
                          type => 'real',
                          font => $font,
                          id => $fontname,
                          priority => $pri,
                          hints => join(' ', @_));

       foreach my $i (@alias) {
         defoma_id_register($Id,
                            type => 'alias',
                            font => $font,
                            id => $i,
                            priority => $pri,
                            origin => $fontname);
       }

       # unregister ids.
       defoma_id_unregister($Id, type => 'alias', font => $font);
       defoma_id_unregister($Id, type => 'real', font => $font);

       # close an id-cache
       defoma_id_close_cache($Id);

       # get a list of indexes of installed fonts that have
       #'Helvetica' for the id.
       my @list = defoma_id_grep_cache($Id, 'installed', id => 'Helvetica');


SEE ALSO
       defoma(1).  Defoma::Font(1).  Defoma::Subst(1).



                                March  4, 2001                 Defoma::Id(3pm)