dictionary-format-v6.txt

   1 This is a quick write-up of the old dictionary file format, v6.
   2 It is the format that is (unfortunately) still used by the Tolino
   3 ebook readers. The ConvertToV6 tool can be used to convert
   4 the new format to this old one.
   5 v6 is troublesome as it relies on Java serialization and thus
   6 there will be references to Java types.
   7 This hasn't been checked much for correctness and likely has some bugs.
   8 Also, I really should have used some standard format for writing this...
   9
  10 ===========================================
  11
  12 Some basic types:
  13
  14 [Short]
  15   2 bytes: big-endian, signed value (note: negative values generally not used here)
  16
  17 [Int]
  18   4 bytes: big-endian, signed value (note: negative values generally not used here)
  19
  20 [Long]
  21   8 bytes: big-endian, signed value (note: negative values generally not used here)
  22
  23
  24 [String]
  25   [Short]: string length
  26   n bytes: string, modified UTF-8, n is value from previous element
  27            note: no zero termination
  28
  29 ======================================================
  30
  31 [Dictionary]
  32
  33 [Int]: version, fixed value 6
  34 [Long]: file creation time (in milliseconds since Jan. 1st 1970)
  35 [String]: dictionary information (human-readable)
  36
  37 list_of([source])
  38 list_of([pair_entry])
  39 list_of([text_entry])
  40 list_of([html_entry]) (since v5)
  41 list_of([index])
  42
  43 [String]: string "END OF DICTIONARY" (length value 17)
  44
  45 ===========================
  46
  47 All list_of entries describe a list of elements.
  48 These elements can have variable size, thus an index (table-of-contents, TOC)
  49 is needed.
  50 To reduce the cost of this table and enable more efficient compression,
  51 multiple entries can be stored in a block that gets one single index entry.
  52 I.e. it is only possible to do random-access to the start of a block,
  53 seeking to elements further inside the block must be done via reading.
  54 Caching should be used to reduce the performance impact of this (so
  55 that when entries 5, 4, 3 etc. of a block are read sequentially,
  56 parsing and decompression is done only once).
  57
  58 These lists have the following base format:
  59
  60 [Int]: number of entries in the list (must be >= 0) (<size>)
  61
  62 <toc size>=<size>*8 + 8 bytes:
  63   table-of-contents.
  64   [Long] offset value for each block of entries.
  65   Followed by a final [Long] offset value to the end of the list data (<end offset>).
  66   Each offset is an absolute file position.
  67
  68 <end offset>-<toc size>-<start of toc> bytes:
  69   entry data
  70
  71 ==========================================================
  72
  73 [source]
  74
  75 [String]: name of source, e.g. "enwiktionary"
  76 [Int]: number of entries from that source (since v3) (I kind of wouldn't rely on that one
  77 being useful/correct...)
  78
  79 ========================================================
  80
  81 [pair entry]
  82
  83 [Short]: source index (see list_of([source])) (since v1)
  84 [Int]: number of pairs in this entry (<num_pairs>)
  85 <num_pairs> times:
  86   [String]: in first language
  87   [String]: in second language (possibly empty)
  88
  89 =================================================
  90
  91 [text_entry]
  92
  93 [Short]: source index (see list_of([source])) (since v1)
  94 [String]: text
  95
  96 ===========================================
  97
  98 [html_entry]
  99
 100 [Short]: source index (see list_of([source])) (since v1)
 101 [String]: title for HTML entry
 102 [Int]: length of decompressed data in bytes (<declen>)
 103 [Int]: length of compressed data in bytes (<len>)
 104 <len> bytes: HTML page data, UTF-8 encoded, gzip compressed
 105
 106 =====================================
 107
 108 [index]
 109
 110 Note: this structure is used for binary search.
 111 It is thus critical that all entries are correctly
 112 sorted.
 113 The sorting is according to libicu, however as Java
 114 and Android versions do not match special hacks
 115 have been added, like ignoring "-" for the comparison
 116 (unless that makes them equal, then they are
 117 compared including the dash).
 118
 119 [String]: index short name
 120 [String]: index long name
 121 [String]: language ISO code (sort order depends on this)
 122 [String]: ICU normalizer rules to apply for sorting/searching
 123 1 byte: swap pair entries (if != 0, this index is for the second language entries in [pair_entry])
 124 [Int]: number of main tokens (?) (since v2)
 125 list_of([index_entry])
 126 [Int]: size of stop list set following (since v4)
 127 Set<String> stop list words (since v4)
 128 uniform_list_of([row])
 129
 130
 131 with uniform_list_of:
 132 [Int]: number of entries in list <num_entries>
 133 [Int]: size of entry <entry_size>
 134 <num_entries>*<entry_size> bytes: data
 135
 136
 137 ================================================
 138
 139 [index_entry]
 140
 141 [String]: token
 142 [Int]: start index into uniform_list_of([row])
 143 [Int]: number of rows covered
 144 1 byte: <has_normalized>
 145 if <has_normalized> != 0:
 146   [String]: normalized token
 147 list_of([Int]) list of indices into list_of(html_entry) (since v6)
 148
 149 =======================================
 150
 151 [row]
 152
 153 1 byte: <type>
 154 [Int]: index
 155
 156 <type> means:
 157 1: index into list_of([pair_entry])
 158 2: index into list_of([index_entry]) (mark as "main word header" entry)
 159 3: index into list_of([text_entry])
 160 4: index into list_of([index_entry]) (mark as "extra info/translation" entry)
 161 5: index into list_of([html_entry])
 162
 163 =======================================
 164
 165 Set<String>
 166
 167 Java serialization of java.util.HashSet.
 168 First part consists always the same 40 bytes:
 169     0xac, 0xed, // magic
 170     0x00, 0x05, // version
 171     0x73, // object
 172     0x72, // class
 173     // Java String "java.util.HashSet"
 174     0x00, 0x11, 0x6a, 0x61, 0x76, 0x61, 0x2e, 0x75, 0x74, 0x69,
 175     0x6c, 0x2e, 0x48, 0x61, 0x73, 0x68, 0x53, 0x65, 0x74,
 176     // serialization ID
 177     0xba, 0x44, 0x85, 0x95, 0x96, 0xb8, 0xb7, 0x34,
 178     0x03, // flags: serialized, custom serialization function
 179     0x00, 0x00, // fields count
 180     0x78, // blockdata end
 181     0x70, // null (superclass)
 182     0x77, 0x0c // blockdata short, 0xc bytes
 183
 184 [Int]: capacity. Not used for anything, but set to >= <num_entries>
 185 [Float]: capacity factor. May affect performance of old QuickDic versions, set to 0.75f
 186 [Int]: <num_entries>
 187 <num_entries> times:
 188     1 byte 0x74: String type
 189     [String]: stop word
 190 1 byte 0x78: blockdata end
 191
 192 Note: Some even older dictionaries wrote out a LinkedHashSet instead of a
 193 HashSet.
 194 That adds the following bytes describing LinkedHashSet before the 0x72 above:
 195     0x72, // class
 196     // Java String "java.util.LinkedHashSet"
 197     0x00, 0x17, 0x6a, 0x61, 0x76, 0x61, 0x2e, 0x75, 0x74, 0x69,
 198     0x6c, 0x2e, 0x4c, 0x69, 0x6e, 0x6b, 0x65, 0x64, 0x48, 0x61,
 199     0x73, 0x68, 0x53, 0x65, 0x74,
 200     // serialization ID
 201     0xd8, 0x6c, 0xd7, 0x5a, 0x95, 0xdd, 0x2a, 0x1e,
 202     0x02, // flags
 203     0x00, 0x00, // fields count
 204     0x78 // blockdata end