data-usr/dbformat.txt

   1 /***@page m17nDatabaseFormat DatabaseFormat
   2
   3 This section describes the formats of predefined @e plist @e type data
   4 in the m17n database.
   5
   6 @section dbformat General format
   7
   8 The m17n library expects that the function mdatabase_load () returns a
   9 plist of a specific format on loading data identified by a specific
  10 set of tags.  As the plist format used for the database data is
  11 strongly limited, we can use the equivalent text of simple syntax
  12 (S-expression) to represent the plist as below.
  13
  14 The text consists of one or more @e elements .  Each element
  15 represents a property, i.e. a single element of a plist, and the
  16 sequence of the elements constitute a plist.
  17
  18 Elements are separated by one or more @e whitespaces, i.e. a space
  19 (code 32), a tab (code 9), or a newline (code 10).  Comments begin
  20 with a semicolon (<tt>;</tt>) and extend to the end of the line.
  21
  22 The key and the value of each property are determined based on the
  23 form of element as below:
  24
  25 <ul>
  26
  27 <li> INTEGER
  28
  29 An element that matches the regular expression @c -?[0-9]+ or @c
  30 0[xX][0-9A-Fa-f]+ represents a property whose key is @c Minteger .  An
  31 element matching the former expression is interpreted as an integer in
  32 decimal notation, and one matching the latter expression is
  33 interpreted as an integer in hexadecimal notation.  The resulting
  34 integer is the value of the property.
  35
  36 For instance, the element 0xA0 represents a property whose value is
  37 the integer 160.
  38
  39 <li> SYMBOL
  40
  41 An element that matchs the regular expression @c
  42 [^-0-9(]([^\\()]|\\.)+ represents a property whose key is @c Msymbol .
  43 In the sequence, @c \\t , @c \\n , @c \\r , and @c \\e are replaced
  44 with tab (code 9), newline (code 10), carriage return (code 13), and
  45 escape (code 27) respectively.  Other characters following a backslash
  46 is interpreted as it is.  The symbol having the name of the resulting
  47 sequence is the value of the property.
  48
  49 For instance, the element <tt>abc\ def</tt> represents a property
  50 whose value is the symbol of name "abc def".
  51
  52 <li> M-TEXT
  53
  54 An element that matches the regular expression @c "([^"]|\\")*"
  55 represents a property whose key is @c Mtext .  The backslash escape
  56 explained above also applies here.  Moreover, each part in the
  57 sequence matching the regular expression @c
  58 \\[xX][0-9A-Fa-f][0-9A-Fa-f] is replaced with its hexadecimal
  59 interpretation.
  60
  61 After having resolved the backslash escapes, the byte sequence between
  62 the double quotes is interpreted as a UTF-8 sequence and decoded into
  63 an M-text.  This M-text is the value of the property.
  64
  65 <li> PLIST
  66
  67 An element that is preceded by a left parenthesis, followed zero or
  68 more elements, and terminated by a right parenthesis represents a
  69 property whose key is @c Mplist .  Parentheses also serve as a
  70 separator, which means whitespaces before and after a parenthesis can
  71 be omitted.  The value of the property is a plist, which is the result
  72 of recursive interpretation of the elements between the parentheses.
  73
  74 </ul>
  75
  76 EXAMPLE
  77
  78 Suppose (K1:V1, K2:V2, ... ,Kn:Vn) represents a plist whose first
  79 property key and value are K1 and V1, second key and value are K2 and
  80 V2, and so on.  Then the line:
  81 @verbatim
  82 abc 123 (pqr 0xff) "m\"text" (_\\_ ("string" xyz) -456)
  83 @endverbatim
  84 is interpreted as follows.
  85 @verbatim
  86 (Msymbol:abc,
  87  Minteger:123,
  88  Mplist:(Msymbol:pqr,
  89          Minteger:255),
  90  Mtext:m"text,
  91  Mplist:(Msymbol:_\_,
  92          Mplist:(Mtext:string,
  93                  Msymbol:xyz),
  94          Minteger:-456))
  95 @endverbatim
  96
  97 The default database loader of the m17n library actually read a text
  98 of this syntax from the database file.
  99
 100 Here after we describes the plist format of each data by this syntax.
 101
 102 @section fontenc Font Encoding
 103
 104 The m17n library loads information about the encoding of each font
 105 form the m17n database by the tags \<font, encoding\>.  The plist
 106 format of the data is as follows:
 107
 108 @verbatim
 109 FONT-ENCODING ::=
 110     '(' PER-FONT-INFO * ')'
 111
 112 PER-FONT-INFO ::=
 113     '(' FONT-SPEC ENCODING ')'
 114
 115 FONT-SPEC ::=
 116     '('
 117     [ FOUNDRY FAMILY [ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ] ] ] ] ] REGISTRY
 118     ')'
 119 @endverbatim
 120
 121 @c FOUNDRY to @c REGISTRY are symbols specifying the corresponding
 122 XLFD font name fields.  Omitted symbols are regarded as @c nil, and
 123 @c nil means a wild card.  For instance, this @c FONT-SPEC:
 124
 125 @verbatim
 126     (nil alice0\ lao iso8859-1)
 127 @endverbatim
 128
 129 should be applied to all fonts whose family is "alice0 lao", and
 130 registry is "iso8859-1".
 131
 132 @c ENCODING is a charset symbol.  A font matching @c FONT-SPEC
 133 supports all characters of the charset, and a character code is mapped
 134 to the corresponding glyph code of the font by this charset.
 135
 136 @section fontsize Font Resizing
 137
 138 In some case, a font contains incorrect information about its size
 139 (typically in the case of a hacked TrueType font), and results in a
 140 bad text layout when such a font is used in combination with the other
 141 fonts.  To overcome this problem, the m17n library loads information
 142 about font-size correction from the m17n database by the tags \<font,
 143 resize\>.  The plist format of the data is as follows:
 144
 145 @verbatim
 146 FONT-RESIZE ::=
 147     '(' PER-FONT-INFO * ')'
 148
 149 PER-FONT-INFO ::=
 150     '(' FONT-SPEC RESIZE-RATIO ')'
 151
 152 FONT-SPEC ::=
 153     '('
 154     [ FOUNDRY FAMILY [ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ] ] ] ] ] REGISTRY
 155     ')'
 156 @endverbatim
 157
 158 The meanings of @c FOUNDRY to @c REGISTRY are the same as @e Font @e
 159 Encoding.  @c RESIZE-RATIO is an integer number specifying by
 160 percentage how much the font-size must be adjusted.  For instance,
 161 this @c PER-FONT-INFO:
 162
 163 @verbatim
 164     ((devanagari-cdac) 150)
 165 @endverbatim
 166
 167 means that, to use a font of registry "devanagari-cdac" with a
 168 specific size, we have to open an 1.5 times bigger one.
 169
 170 @section fontset Fontset
 171
 172 The m17n library loads a fontset definition from the m17n database by
 173 the tags \<fontset, FONTSET-NAME\>.  The plist format of the data is
 174 as follows:
 175
 176 @verbatim
 177 FONTSET ::=
 178     '(' PER-SCRIPT + ')'
 179
 180 PER-SCRIPT ::=
 181     '(' SCRIPT PER-LANGUAGE + ')'
 182
 183 PER-LANGUAGE ::=
 184     '(' LANGUAGE FONT-SPEC-ELEMENT + ')'
 185
 186 FONT-SPEC-ELEMENT ::=
 187     '(' FONT-SPEC [ FLT-NAME ] ')'
 188
 189 FONT-SPEC ::=
 190     '('
 191     [ FOUNDRY FAMILY [ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ] ] ] ] ] REGISTRY
 192     ')'
 193 @endverbatim
 194
 195 @c SCRIPT is a symbol of script name (e.g. latin, han), or @c nil.  @c
 196 LANGUAGE is a two-letter symbol of language name code defined by ISO
 197 639 (e.g. ja, zh) or @c nil.  The meanings of @c FOUNDRY to @c
 198 REGISTRY are the same as @e Font @e Encoding.  @c FLT-NAME is a name
 199 of @ref flt.
 200
 201 For instance, this @c PER_SCRIPT:
 202
 203 @verbatim
 204 (han
 205   (ja
 206     ((jisx0208.1983-0)))
 207   (zh
 208     ((gb2312.1980-0)))
 209   (nil
 210     ((big5-0))))
 211 @endverbatim
 212
 213 instructs the rendering engine to use a font of registry
 214 "jisx0208.1983-0" for a "han" character that has @c Mlanguage text
 215 propert "ja" if the character is in the repertories of such fonts.
 216 Otherwise, try a font of registry "gb2312.1980-0" or "big5-0".  If a
 217 "han" character doesn not have @c Mlangauge text property, try all
 218 three fonts.
 219
 220 @section flt Font Layout Table
 221
 222 Usually, the rendering engine converts character codes of a text into
 223 glyph codes one by one by consulting information about encoding of
 224 each selected font.  But, for rendering a text that requires
 225 complicated layouting (e.g. Thai and Indic), such an one to one
 226 conversion is not sufficient.  In addition, some glyphs must be
 227 shifted 2-dimensionally on the screen.  For such a case, a font layout
 228 table (FLT in short) must be used.
 229
 230 A FLT can contain all the information in OpenType Layout Table (CMAP,
 231 GSUB, and GPOS) in addition to the information about how to extract a
 232 grapheme cluster and how to re-order characters.
 233
 234 The m17n library loads a FLT from the m17n database by the tags
 235 \<font, layouter, FLT-NAME\>.  The plist format of the data is as
 236 follows:
 237
 238 @verbinclude flt.txt
 239
 240 @section im Input Method
 241
 242 @verbinclude im.txt
 243
 244 */
 245
 246 ////