data/dbformat.txt

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