data-usr/dbformat.txt

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