Debian Codegraph @

format_docs/rb.txt

raw
1 Rocket eBook File Format
2 ------------------------
3
4 from http://rbmake.sourceforge.net/rb_format.html
5
6
7 Overview
8 --------
9
10 This document attempts to describe the format of a .rb file -- the book
11 format that is downloaded into NuvoMedia's <http://www.nuvomedia.com>
12 hand-held wonder, the Rocket eBook
13 <http://www.rocket-ebook.com/enter.html>.
14
15 *Note:* All multi-byte integers are stored in Vax/Intel order (the
16 opposite of network byte order). Most integers are 4 bytes (an int32),
17 but there are some minor exceptions (as detailed below).
18
19 Also, the following document refers to the .rb file sections as "pages".
20
21
22 Details
23 -------
24
25 The first 4 bytes of the file seem to be a magic number (in hex): B0 0C
26 B0 0C. I like to think of this as a hexadecimal pun on the word "book"
27 (repeated). [Matt Greenwood has reported seeing a magic number of "B0 0C
28 F0 0D" in another type of ReB-related file -- i.e. "book food".]
29
30 The next two bytes appear to be a version number, currently "02 00". I
31 assume this means major version 2, minor version 0.
32
33 The next 4 bytes are the string "NUVO", followed by 4 bytes of 00h. (I
34 have also seen an old title that had 0s in place of the "NUVO".)
35
36 This brings us up to offset 0Eh, at which point we have a 4-byte
37 representation of the date the book was created (Matt Greenwood pointed
38 this out to me -- thanks!). The year is encoded as an int16. On older
39 version of the RocketLibrary was encoding the year's full value (e.g.
40 1999 was "CF 07" and 2000 was "D0 07"), but a more recent version is now
41 using the tm_year value verbatim -- i.e. it's storing 100 for the year
42 2000 ("64 00"). The year is followed by an int8 for the 1-relative month
43 number, and an int8 for the day of the month.
44
45 After that is 6 bytes of 00h. These may be reserved for setting the time
46 of creation (at a guess).
47
48 Then, at offset 18h, we have an int32 that contains the absolute offset
49 of the "Table of Contents" (the directory of the pages contained within
50 this .rb file). In all of the .rb file's I've seen, this remains
51 constant with a value of 128h. However, I have tested an atypical .rb
52 file where I placed the ToC at the end of the file (after all the file
53 contents), and it worked fine. (I've chosen not to build any books in
54 such a non-standard format, however.)
55
56 Immediately following this is an int32 with the length of the .rb file
57 (so we can check if the file is complete or not).
58
59 All the bytes from here (offset 20h) up to offset 128h appear to only be
60 used by an encrypted title. In a non-encrypted title, they are always 0.
61
62 The table of contents typically comes next (at offset 128h). It starts
63 with an int32 count of the number of "page" entries (.rb-file sections)
64 in the ToC. Each entry consists of a name (zero-padded to 32 bytes),
65 followed by 3 int32s: the length of this entry's data segment, the
66 absolute offset of the data in the .rb file, and a flag. The known flag
67 values are: 1 (encrypted), 2 (info page), and 8 (deflated). The names
68 are tweaked as needed to ensure that they are all unique. The current
69 RocketWriter software uses a unique 6-digit number, a dash, up to 8
70 characters from the filename, and then the re-mapped suffix for the data
71 (.html, .hidx, .png, .info, etc.). My rbmake library simply ensures that
72 the names are no longer than 15 characters (not counting the suffix) and
73 are all unique.
74
75 Often the first item in the ToC is the info page, but it doesn't have to
76 be. This page of information contains NAME=VALUE pairs that note the
77 author, title, what the root-page's name is, etc. (See appendix A). This
78 data is never encrypted nor compressed, so this entry's flag value is
79 always "2".
80
81 An image page is always stored as a B&W image in PNG format. Since it
82 has its own compression, it is stored without any additional attempt at
83 deflation. I have also never seen an encrypted image, so its flag value
84 is always 0.
85
86 An HTML page contains the tags and text that were re-written into a
87 consistent syntax (this presumably makes the HTML renderer in the ReB
88 itself simpler). HTML pages are typically compressed (See appendix B).
89 Every HTML page appears to use the suffix .html no matter what the file
90 name was on import (but I have seen older files with .htm used as the
91 suffix, so the rocket appears to support both).
92
93 For every HTML page there is a corresponding .hidx page that contains a
94 summary of the paragraph formatting and the position of the anchor names
95 in the associated .html page (See appendix C). This page is sometimes
96 compressed, depending on length (See appendix B).
97
98 There are also reference titles that have a .hkey page that contains a
99 list of words that can be looked up in the associated .html page (See
100 appendix D).
101
102 Immediately following the ToC is the data for each piece mentioned in
103 the ToC, in the same order as it appeared in the ToC.
104
105 Finally, the end of the file appears to be padded with 20 bytes of 01h.
106
107
108 Appendix A: Info Page Format
109 ----------------------------
110
111 The info page consists of a series of lines that contain "NAME=VALUE"
112 strings. Each line is terminated by a single newline. Here are the
113 values that the RocketWriter generates:
114
115 COMMENT=Info file for <title>
116 TYPE=2
117 TITLE=<title>
118 AUTHOR=<author>
119 URL=ebook:<long, unique string used for the file's name by the librarian>
120 GENERATOR=<e.g. RocketLibrarian 1.3.216>
121 PARSE=1
122 OUTPUT=1
123 BODY=<name of root HTML page (as it appears in the ToC)>
124 MENUMARK=menumark.html
125 SuggestedRetailPrice=<usually empty>
126
127 Encrypted titles have a few more entries (including those listed above):
128
129 ISBN=<ISBN, including dashes>
130 REVISION=<digits>
131 TITLE_LANGUAGE=<en-us>
132 PUB_NAME=<Publisher's name>
133 PUBSERVER_ID=<digits>
134 GENERATOR=<e.g. RocketPress 1.3.121>
135 VERSION=<digits>
136 USERNAME=<rocket-ID>
137 COPY_ID=<digits>
138 COPYRIGHT=<copyright>
139 COPYTITLE=<another copyright?>
140
141 A reference title also has an indication that there is a .hkey page
142 present, and may also have a GENRE of "Reference":
143
144 HKEY=1
145 GENRE=Reference
146
147
148 Appendix B: The format of compressed data
149 -----------------------------------------
150
151 Compressed pages have a data section in the .rb file with the following
152 format:
153
154 The first int32 is a count of the number of 4096-byte chunks of data we
155 broke the uncompressed page into (the last chunk can be shorter than
156 4096 bytes, of course).
157
158 This is immediately followed by an int32 with the length of the entire
159 uncompressed data.
160
161 After this there are <count> int32s that indicate the size of each
162 chunk's compressed data.
163
164 Following these length int32s is the output from a deflation (the
165 algorithm used in gzip) for each 4096-byte chunk of the original data.
166 It appears that you must use a window-bit size of 13 and a compression
167 level of "best" to be compatible with the Rocket eBook's system software.
168
169
170 Appendix C: HTML-index Page Format
171 ----------------------------------
172
173 The .hidx page's purpose is to allow the renderer to quickly look up the
174 format of each paragraph (useful for random access to the data), and the
175 position of the anchor names.
176
177 The first section lists the various paragraph-producing tags. It is
178 headed by a line of "[tags <count>]", where <count> is the number of
179 tags that follow this header. The tags are listed one per line, and have
180 an implied enumeration from 0 to N-1 (which the other tags and the
181 upcoming paragraph sections reference).
182
183 The first tag is typically (always?) "<HTML> -1". The number trailing
184 the tag indicates what other tag (or sequence of tags, one per line) in
185 which we are nested. So, if we have a <BR> nested inside a <P
186 ALIGN="center">, it would be listed separately from a <BR> that was
187 nested inside a normal paragraph, and each one would have a different
188 trailing index number.
189
190 Following the tag section is the paragraph section. The heading is
191 "[paragraphs <count>]", and is followed by a line for each paragraph.
192 These lines consist of a character offset into the .html page for the
193 start of the paragraph followed by a 0-relative offset into the tag
194 section (indicating what kind of formatting to use for the indicated
195 paragraph).
196
197 The paragraph-section character offsets point to the first bit of text
198 after the associated tag.
199
200 The last section details the anchor names. The heading is
201 "[names <count>]", and each item that follows is a quoted string of the
202 anchor name, followed by a character offset into the .html page where
203 we'll find that name. If there are no names in the associated HTML
204 section, the heading is included with a 0 count (i.e. "[names 0]").
205
206 The name-section character offsets point to the start of the anchor tag
207 (not after the tag, like the offsets in the "paragraphs" section).
208
209 The lines are terminated by newlines (in standard unix fashion).
210
211 For example:
212
213 [tags 10]
214 <HTML> -1
215 <BODY> 0
216 <P ALIGN="right"> 1
217 <P ALIGN="left"> 1
218 <P> 1
219 <H3 ALIGN="center"> 1
220 <P ALIGN="center"> 1
221 <BR> 6
222 <H2 ALIGN="center"> 1
223 <BR> 1
224
225 [paragraphs 42]
226 160 9
227 164 9
228 184 8
229 220 8
230 261 6
231 316 5
232 359 1
233 379 6
234 410 6
235 460 7
236 511 7
237 564 7
238 616 7
239 668 7
240 720 7
241 773 7
242 827 7
243 880 7
244 933 7
245 988 7
246 1043 7
247 1100 7
248 1157 7
249 1214 7
250 1270 7
251 1328 7
252 1385 7
253 1442 7
254 1497 7
255 1556 7
256 1561 7
257 1635 1
258 1656 5
259 1690 6
260 1737 7
261 1773 5
262 1798 4
263 1826 3
264 2663 1
265 2668 4
266 2689 2
267 2730 8
268
269 [names 1]
270 "ch1" 2689
271
272
273 Appendix D: HTML-key Page Format
274 --------------------------------
275
276 The .hkey page contains a list of words, one per line, sorted in a
277 strict ASCII sequence, each one followed by a tab and the offset in the
278 .html page of the word's data. I presume that the .hkey page must share
279 the same name prefix as its related .html page.
280
281 If the names contain high-bit characters, they are translated into
282 regular ASCII in the .hkey file, since this allows the user to search
283 for the words using unaccented characters.
284
285 The lines are terminated with a newline (in standard unix fashion).
286
287 An example:
288
289 a 5
290 apple 38
291 b 84
292 book 104
293
294 Each of these offsets points to a paragraph tag in the associated .html
295 page. I have only seen this sequence of tags used so far:
296
297 <P><BIG><B>word</B></BIG> other stuff</P>
298
299 I have seen multiple <B>...</B> tags in the middle of the single set of
300 <BIG>...</BIG> tags, but this is the basic tag format.
301
302 The offset in the .hkey page points to the start of the <P> tag.
303