| 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 |
|