A fork of https://github.com/crosspoint-reader/crosspoint-reader
Replace book and section bin format images with ImHex hexpat definition (#189)
## Summary
* Replace book and section bin format images with ImHex hexpat
definition
* This should give readers an understanding of the file format but also
supply some utility when validating content/output
authored by
Dave Allie
and committed by
GitHub
04ad4e5a
6e9ba100
+214
-2
+214
-2
docs/file-formats.md
+214
-2
docs/file-formats.md
···
2
2
3
3
## `book.bin`
4
4
5
-
5
+
### Version 3
6
+
7
+
ImHex Pattern:
8
+
9
+
```c++
10
+
import std.mem;
11
+
import std.string;
12
+
import std.core;
13
+
14
+
// === Configuration ===
15
+
#define EXPECTED_VERSION 3
16
+
#define MAX_STRING_LENGTH 65535
17
+
18
+
// === String Structure ===
19
+
20
+
struct String {
21
+
u32 length [[hidden, comment("String byte length")]];
22
+
if (length > MAX_STRING_LENGTH) {
23
+
std::warning(std::format("Unusually large string length: {} bytes", length));
24
+
}
25
+
char data[length] [[comment("UTF-8 string data")]];
26
+
} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
27
+
28
+
fn format_string(String s) {
29
+
return s.data;
30
+
};
31
+
32
+
// === Metadata Structure ===
33
+
34
+
struct Metadata {
35
+
String title [[comment("Book title")]];
36
+
String author [[comment("Book author")]];
37
+
String coverItemHref [[comment("Path to cover image")]];
38
+
String textReferenceHref [[comment("Path to guided first text reference")]];
39
+
} [[comment("Book metadata information")]];
40
+
41
+
// === Spine Entry Structure ===
42
+
43
+
struct SpineEntry {
44
+
String href [[comment("Resource path")]];
45
+
u32 cumulativeSize [[comment("Cumulative size in bytes"), color("FF6B6B")]];
46
+
s16 tocIndex [[comment("Index into TOC (-1 if none)"), color("4ECDC4")]];
47
+
} [[comment("Spine entry defining reading order")]];
48
+
49
+
// === TOC Entry Structure ===
50
+
51
+
struct TocEntry {
52
+
String title [[comment("Chapter/section title")]];
53
+
String href [[comment("Resource path")]];
54
+
String anchor [[comment("Fragment identifier")]];
55
+
u8 level [[comment("Nesting level (0-255)"), color("95E1D3")]];
56
+
s16 spineIndex [[comment("Index into spine (-1 if none)"), color("F38181")]];
57
+
} [[comment("Table of contents entry")]];
58
+
59
+
// === Book Bin Structure ===
60
+
61
+
struct BookBin {
62
+
// Header
63
+
u8 version [[comment("Format version"), color("FFD93D")]];
64
+
65
+
// Version validation
66
+
if (version != EXPECTED_VERSION) {
67
+
std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
68
+
}
69
+
70
+
u32 lutOffset [[comment("Offset to lookup tables"), color("6BCB77")]];
71
+
u16 spineCount [[comment("Number of spine entries"), color("4D96FF")]];
72
+
u16 tocCount [[comment("Number of TOC entries"), color("FF6B9D")]];
73
+
74
+
// Metadata section
75
+
Metadata metadata [[comment("Book metadata")]];
76
+
77
+
// Validate LUT offset alignment
78
+
u32 currentOffset = $;
79
+
if (currentOffset != lutOffset) {
80
+
std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
81
+
}
82
+
83
+
// Lookup Tables
84
+
u32 spineLut[spineCount] [[comment("Spine entry offsets"), color("4D96FF")]];
85
+
u32 tocLut[tocCount] [[comment("TOC entry offsets"), color("FF6B9D")]];
86
+
87
+
// Data Entries
88
+
SpineEntry spines[spineCount] [[comment("Spine entries (reading order)")]];
89
+
TocEntry toc[tocCount] [[comment("Table of contents entries")]];
90
+
};
91
+
92
+
// === File Parsing ===
93
+
94
+
BookBin book @ 0x00;
95
+
96
+
// Validate we've consumed the entire file
97
+
u32 fileSize = std::mem::size();
98
+
u32 parsedSize = $;
99
+
100
+
if (parsedSize != fileSize) {
101
+
std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
102
+
}
103
+
```
6
104
7
105
## `section.bin`
8
106
9
-
107
+
### Version 8
108
+
109
+
ImHex Pattern:
110
+
111
+
```c++
112
+
import std.mem;
113
+
import std.string;
114
+
import std.core;
115
+
116
+
// === Configuration ===
117
+
#define EXPECTED_VERSION 8
118
+
#define MAX_STRING_LENGTH 65535
119
+
120
+
// === String Structure ===
121
+
122
+
struct String {
123
+
u32 length [[hidden, comment("String byte length")]];
124
+
if (length > MAX_STRING_LENGTH) {
125
+
std::warning(std::format("Unusually large string length: {} bytes", length));
126
+
}
127
+
char data[length] [[comment("UTF-8 string data")]];
128
+
} [[sealed, format("format_string"), comment("Length-prefixed UTF-8 string")]];
129
+
130
+
fn format_string(String s) {
131
+
return s.data;
132
+
};
133
+
134
+
// === Page Structure ===
135
+
136
+
enum StorageType : u8 {
137
+
PageLine = 1
138
+
};
139
+
140
+
enum WordStyle : u8 {
141
+
REGULAR = 0,
142
+
BOLD = 1,
143
+
ITALIC = 2,
144
+
BOLD_ITALIC = 3
145
+
};
146
+
147
+
enum BlockStyle : u8 {
148
+
JUSTIFIED = 0,
149
+
LEFT_ALIGN = 1,
150
+
CENTER_ALIGN = 2,
151
+
RIGHT_ALIGN = 3,
152
+
};
153
+
154
+
struct PageLine {
155
+
s16 xPos;
156
+
s16 yPos;
157
+
u16 wordCount;
158
+
String words[wordCount];
159
+
u16 wordXPos[wordCount];
160
+
WordStyle wordStyle[wordCount];
161
+
BlockStyle blockStyle;
162
+
};
163
+
164
+
struct PageElement {
165
+
u8 pageElementType;
166
+
if (pageElementType == 1) {
167
+
PageLine pageLine [[inline]];
168
+
} else {
169
+
std::error(std::format("Unknown page element type: {}", pageElementType));
170
+
}
171
+
};
172
+
173
+
struct Page {
174
+
u16 elementCount;
175
+
PageElement elements[elementCount] [[inline]];
176
+
};
177
+
178
+
// === Section Bin Structure ===
179
+
180
+
struct SectionBin {
181
+
// Header
182
+
u8 version [[comment("Format version"), color("FFD93D")]];
183
+
184
+
// Version validation
185
+
if (version != EXPECTED_VERSION) {
186
+
std::error(std::format("Unsupported version: {} (expected {})", version, EXPECTED_VERSION));
187
+
}
188
+
189
+
// Cache busting parameters
190
+
s32 fontId;
191
+
float lineCompression;
192
+
bool extraParagraphSpacing;
193
+
u16 viewportWidth;
194
+
u16 vieportHeight;
195
+
u16 pageCount;
196
+
u32 lutOffset;
197
+
198
+
Page page[pageCount];
199
+
200
+
// Validate LUT offset alignment
201
+
u32 currentOffset = $;
202
+
if (currentOffset != lutOffset) {
203
+
std::warning(std::format("LUT offset mismatch: expected 0x{:X}, got 0x{:X}", lutOffset, currentOffset));
204
+
}
205
+
206
+
// Lookup Tables
207
+
u32 lut[pageCount];
208
+
};
209
+
210
+
// === File Parsing ===
211
+
212
+
SectionBin book @ 0x00;
213
+
214
+
// Validate we've consumed the entire file
215
+
u32 fileSize = std::mem::size();
216
+
u32 parsedSize = $;
217
+
218
+
if (parsedSize != fileSize) {
219
+
std::warning(std::format("Unparsed data detected: {} bytes remaining at offset 0x{:X}", fileSize - parsedSize, parsedSize));
220
+
}
221
+
```
docs/images/file-formats/book-bin.png
docs/images/file-formats/book-bin.png
This is a binary file and will not be displayed.
docs/images/file-formats/section-bin.png
docs/images/file-formats/section-bin.png
This is a binary file and will not be displayed.