class/I18N/README

   1
   2 I18N: Pnetlib Internationalization Framework Libary
   3 ===================================================
   4
   5 Using the library
   6 -----------------
   7
   8 This library provides plug-in i18n module support for C# base class
   9 libraries such as pnetlib's "runtime".  The base class library uses
  10 it as follows:
  11
  12     - Load the "I18N.dll" assembly using "System.Reflection.Assembly.Load".
  13
  14     - Obtain the value of the static "PrimaryManager" property within the
  15       "I18N.Common.Manager" class using "System.Reflection" facilities.
  16
  17     - Invoke methods on the manager class to obtain i18n-sensitive
  18       objects such as "CultureInfo" and "Encoding" instances.
  19
  20     - The "I18N.Common.Manager" class loads the requested i18n object
  21       and returns it to the base class library, which can then use it
  22       in the usual fashion.
  23
  24 A more detailed example is given in a later section.
  25
  26 I18N handlers
  27 -------------
  28
  29 Because there are so many i18n-sensitive cases to be handled, the culture
  30 information has been split across several region-specific assemblies:
  31
  32     I18N.CJK.dll
  33     I18N.MidEast.dll
  34     I18N.Other.dll
  35     I18N.Rare.dll
  36     I18N.West.dll
  37
  38 The "I18N.dll" assembly only loads those region-specific assemblies that
  39 it needs, based on the user's requests.
  40
  41 I18N handlers within these assemblies use the naming convention
  42 "I18N.<Region>.<Prefix><Value>" where:
  43
  44     <Region>
  45         The region handler.  e.g. "West", "CJK", "India", etc.
  46
  47     <Prefix>
  48         The prefix for the handler type.
  49
  50     <Value>
  51         The identifier value which is supplied by the caller.
  52         e.g. a culture identifier, an encoding name, etc.
  53
  54 The following prefixes are supported:
  55
  56     CP
  57         Code page handler.  e.g. "CP1252".
  58
  59     ENC
  60         Web encoding handler.  e.g. "ENCiso_8869_8".
  61
  62     CID
  63         Culture, based on identifier.  e.g. "CID2c01".
  64
  65     CIDO
  66
  67         Culture, based on identifier, with user overrides.  e.g. "CIDO2c01".
  68         Falls back to the "CID" handler if no override handler.
  69
  70     CN
  71         Culture, based on name.  e.g. "CNar_jo".
  72
  73     CNO
  74         Culture, based on name, with user overrides.  e.g. "CNOar_jo".
  75         Falls back to the "CN" handler if no override handler.
  76
  77 Handlers that are based on name will normalize the name to be in all
  78 lower case, with all instances of '-' replaced with '_'.
  79
  80 The "I18N.dll" assembly knows which region assembly to load from the
  81 "I18N-handlers.def" file.  This file is automatically generated during
  82 the build process and contains a list of all I18N handler classes.
  83 It must reside in the same directory as "I18N.dll".
  84
  85 Example
  86 -------
  87
  88 As an example of the I18N loading process, we will describe what happens
  89 when code page 932 is requested:
  90
  91     - The user's code calls "System.Text.Encoding.GetEncoding(932)".
  92
  93     - The "Encoding" class loads "I18N.dll" using reflection.
  94
  95     - The "Encoding" class accesses the "PrimaryManager" property via
  96       reflection to get an instance of "I18N.Common.Manager".
  97
  98     - The "Encoding" class calls the "GetEncoding(int)" method on
  99       the "I18N.Common.Manager" instance using reflection.
 100
 101     - "I18N.Common.Manager" constructs the name of the handler class - "CP932".
 102
 103     - The file "I18N-handlers.def" is consulted to determine the full
 104       namespace and name of the "CP932" class - "I18N.CJK.CP932".
 105
 106     - The region assembly "I18N.CJK.dll" is loaded using reflection.
 107
 108     - An instance of the class "I18N.CJK.CP923" in the loaded assembly
 109       is constructed and returned to the caller.
 110
 111 The results of previous requests are cached to smooth overall performance
 112 of the system.
 113
 114 Dependencies
 115 ------------
 116
 117 This section describes the facilities that must be available from the
 118 base class library to make the I18N framework function.
 119
 120 The framework makes heavy use of facilities from "System.Reflection"
 121 to load assemblies and to access their contents.
 122
 123 String resources are assumed to be embedded as manifest string resources,
 124 based on tag names.  The "I18N.Common.Strings" class takes care of the
 125 resource needs of all of the I18N assemblies.  It relies upon a working
 126 implementation of "ResourceManager", that can load and process manifest
 127 string resources.
 128
 129 It is assumed that the base class library contains its own implementation
 130 of the invariant culture.  i.e. the invariant culture cannot be loaded
 131 dynamically.
 132
 133 The "I18N.CJK.dll" assembly contains a single "InternalCall" method in
 134 the "I18N.CJK.CodeTable" class if the "__PNET__" symbol is defined when
 135 the assembly is compiled.  This gives more efficient access to conversion
 136 CJK tables when running on the Portable.NET runtime engine.  If the
 137 "__PNET__" symbol is not defined, then the implementation will fall back
 138 to a less efficient way of loading the tables.
 139
 140 The method "System.Reflection.Assembly.GetFile(String)" is assumed to
 141 have slightly different semantics to the .NET Framework SDK.  Normally,
 142 this method accesses a file that is listed in the assembly manifest.
 143 We have extended it so that it can also access files in the same directory
 144 as the assembly, even if not mentioned in the manifest.
 145
 146 The altered semantics is necessary to access the "I18N-handlers.def" file,
 147 which defines which assembly contains which I18N handler.  This file can
 148 be altered by third parties to install new handler assemblies.
 149
 150 If the runtime engine does not implement the altered "GetFile" semantics,
 151 the library will fall back to an internal list that must be maintained
 152 internally and which cannot be dynamically extended by third parties.
 153
 154 Security considerations
 155 -----------------------
 156
 157 The "GetAddress" and "GetFile" methods need to be implemented carefully
 158 to prevent arbitrary applications using them to circumvent system security.