data-usr/dbformat.txt

   1 /***@page m17nDatabaseFormat Data Format of the m17n database
   2
   3 This section describes formats of data in the m17n database.
   4
   5 @section dbformat General format
   6
   7 The mdatabase_load () function returns the data specified by tags in
   8 the form of plist if the first tag is not @c Mchartable nor @c
   9 Mcharset.  The keys of the returned plist are limited to
  10 <tt>Minteger</tt>, <tt>Msymbol</tt>, <tt>Mtext</tt>, and
  11 <tt>Mplist</tt>.  The type of the value is unambiguously determined by
  12 the corresponding key.  If the key is <tt>Minteger</tt>, the value is
  13 an integer.  If the key is <tt>Msymbol</tt>, the value is a symbol.
  14 And so on.
  15
  16 A number of expressions are possible to represent a plist.  For
  17 instance, we can use the form <tt>(K1:V1, K2:V2, ..., Kn:Vn)</tt> to
  18 represent a plist whose first property key and value are K1 and V1,
  19 second key and value are K2 and V2, and so on.  However, we can use a
  20 simpler expression here because the types of plists used in the m17n
  21 database are fairly restricted.
  22
  23 Hereafter, we use an expression, which is similar to S-expression, to
  24 represent a plist.  (Actually, the default database loader of the m17n
  25 library is designed to read data files written in this expression.)
  26
  27 The expression consists of one or more <i>elements</i>.  Each element
  28 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 symbol representing a charset.  A font matching @c
 142 FONT-SPEC supports all characters of the charset, and a character code
 143 is mapped to the corresponding glyph code of the font by this charset.
 144
 145
 146 @section fontsize Font Resizing
 147
 148 In some case, a font contains incorrect information about its size
 149 (typically in the case of a hacked TrueType font), which results in a
 150 bad text layout when such a font is used in combination with the other
 151 fonts.  To overcome this problem, the m17n library loads information
 152 about font-size correction from the m17n database by the tags \<font,
 153 resize\>.  The plist format of the data is as follows:
 154
 155 @verbatim
 156 FONT-RESIZE ::=
 157     PER-FONT-INFO *
 158
 159 PER-FONT-INFO ::=
 160     '(' FONT-SPEC RESIZE-RATIO ')'
 161
 162 FONT-SPEC ::=
 163     '('
 164     [ FOUNDRY FAMILY [ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ] ] ] ] ] REGISTRY
 165     ')'
 166 @endverbatim
 167
 168 The meanings of @c FOUNDRY to @c REGISTRY are the same as @e Font @e
 169 Encoding.  @c RESIZE-RATIO is an integer number specifying by
 170 percentage how much the font-size must be adjusted.  For instance,
 171 this @c PER-FONT-INFO:
 172
 173 @verbatim
 174     ((devanagari-cdac) 150)
 175 @endverbatim
 176
 177 means that, to use a font of registry "devanagari-cdac" with a
 178 specific size, we have to open an 1.5 times bigger one.
 179
 180 @section fontset Fontset
 181
 182 The m17n library loads a fontset definition from the m17n database by
 183 the tags \<fontset, FONTSET-NAME\>.  The plist format of the data is
 184 as follows:
 185
 186 @verbatim
 187 FONTSET ::=
 188     PER-SCRIPT +
 189
 190 PER-SCRIPT ::=
 191     '(' SCRIPT PER-LANGUAGE + ')'
 192
 193 PER-LANGUAGE ::=
 194     '(' LANGUAGE FONT-SPEC-ELEMENT + ')'
 195
 196 FONT-SPEC-ELEMENT ::=
 197     '(' FONT-SPEC [ FLT-NAME ] ')'
 198
 199 FONT-SPEC ::=
 200     '('
 201     [ FOUNDRY FAMILY [ WEIGHT [ STYLE [ STRETCH [ ADSTYLE ] ] ] ] ] REGISTRY
 202     ')'
 203 @endverbatim
 204
 205 @c SCRIPT is a symbol of script name (e.g. latin, han) or @c nil.  @c
 206 LANGUAGE is a two-letter symbol of language name code defined by ISO
 207 639 (e.g. ja, zh) or @c nil.  The meanings of @c FOUNDRY to @c
 208 REGISTRY are the same as @e Font @e Encoding.  @c FLT-NAME is a name
 209 of @ref flt.
 210
 211 For instance, this @c PER_SCRIPT:
 212
 213 @verbatim
 214 (han
 215   (ja
 216     ((jisx0208.1983-0)))
 217   (zh
 218     ((gb2312.1980-0)))
 219   (nil
 220     ((big5-0))))
 221 @endverbatim
 222
 223 instructs the rendering engine to use a font of registry
 224 "jisx0208.1983-0" for a "han" character that has @c Mlanguage text
 225 propert "ja" if the character is in the repertories of such fonts.
 226 Otherwise, try a font of registry "gb2312.1980-0" or "big5-0".  If a
 227 "han" character does not have @c Mlangauge text property, try all
 228 three fonts.
 229
 230 @section flt Font Layout Table
 231
 232 Usually, the rendering engine converts character codes of into glyph
 233 codes one by one by consulting information about encoding of each
 234 selected font.  But, for rendering a text that requires complicated
 235 layouting (e.g. Thai and Indic), such an one to one conversion is not
 236 sufficient.  In addition, some glyphs must be shifted 2-dimensionally
 237 on the screen.  For such a case, a font layout table (FLT in short)
 238 must be used.
 239
 240 A FLT can contain the information equivarent to OpenType Layout Table
 241 (CMAP, GSUB, and GPOS) in addition to the information about how to
 242 extract a grapheme cluster and how to re-order characters.
 243
 244 The m17n library loads a FLT from the m17n database by the tags
 245 \<font, layouter, FLT-NAME\>.  The plist format of the data is as
 246 follows:
 247
 248 @verbinclude flt.txt
 249
 250 @section im Input Method
 251
 252 @verbinclude im.txt
 253
 254 */
 255
 256 ////