Reformat RAC spec example; link to ref impl
diff --git a/doc/spec/rac-spec.md b/doc/spec/rac-spec.md index 2dee8c3..bf79c63 100644 --- a/doc/spec/rac-spec.md +++ b/doc/spec/rac-spec.md
@@ -187,6 +187,9 @@ | CPtr[A] |V|A| CPtr[Arity] a.k.a. CPtrMax, Version, Arity +-+-+-+-+-+-+-+-+ +See the "Examples" section below for example RAC files and, in particular, +example `Branch Node`s. + For the `(XPtr | Other6 | Other7)` 8 byte fields, the `XPtr` occupies the low 48 bits (as a little-endian `uint64_t`) and the `Other` fields occupy the high 16 bits. @@ -542,8 +545,9 @@ # Examples These examples display RAC files in the format of the `hexdump -C` command line -tool. They are deliberately very short, for ease of understanding, and -therefore exhibit unusually bad compression ratios. +tool. They are deliberately very short, for ease of understanding. Realistic +RAC files, with larger chunk sizes, would typically exhibit much better +compression ratios. ## Zlib Example (Root Node at End) @@ -587,6 +591,9 @@ The third example demonstrates concatenating two RAC files: the two examples above. The decompressed form of the resultant RAC file is the concatenation of the two decompressed forms: "One sheep.\nTwo sheep.\nThree sheep.\nMore!\n". +Its 41 decompressed bytes consists of the "sheep" RAC file's 35 bytes and then +the "more" RAC file's 6 bytes. In hexadecimal, `0x29 = 0x23 + 0x06`, and the +`0x29` and `0x23` numbers can be seen in the compressed form's bytes. The compressed form (what's shown in `hexdump -C` format below) is the concatenation of the two compressed forms, plus a new root node (64 bytes @@ -627,26 +634,34 @@ 00000100 00 00 04 01 b4 00 00 00 00 00 04 00 14 01 00 00 00000110 00 00 01 03 -Re-formatting to highlight the multiple-of-8-bytes structure: +Re-formatting to highlight the groups-of-8-bytes structure and reprise the +"Branch Nodes" section's diagram: - 000000d4 72 c3 63 03 f8 ec 00 ff - 000000dc 00 00 00 00 00 00 00 fe - 000000e4 23 00 00 00 00 00 00 fe - 000000ec 29 00 00 00 00 00 00 01 - -------- - 000000f4 9f 00 00 00 00 00 00 ff - 000000fc 00 00 00 00 00 00 04 01 - 00000104 b4 00 00 00 00 00 04 00 - 0000010c 14 01 00 00 00 00 01 03 + 000000d4 72 c3 63 03 f8 ec 00 ff |Magic|A|Che|0|T| + 000000dc 00 00 00 00 00 00 00 fe | DPtr[1] |0|T| + 000000e4 23 00 00 00 00 00 00 fe | DPtr[2] |0|T| + 000000ec 29 00 00 00 00 00 00 01 | DPtr[A] |0|C| + 000000f4 9f 00 00 00 00 00 00 ff | CPtr[0] |L|S| + 000000fc 00 00 00 00 00 00 04 01 | CPtr[1] |L|S| + 00000104 b4 00 00 00 00 00 04 00 | CPtr[2] |L|S| + 0000010c 14 01 00 00 00 00 01 03 | CPtr[A] |V|A| Its `Codec` is `0x01`, "RAC + Zlib", its Version is `0x01` and its `Arity` is `0x03`. The `DPtr` values are `0x0000` (implicit), `0x0000`, `0x0023` and `0x0029`. The `CPtr` values are `0x009F`, `0x0000`, `0x00B4` and `0x0114` (the size of the whole RAC file). Note that the `CPtr` values are not sorted. The -two branch nodes' `TTag`s are `0xFE` and `0xFE` and their `STag`s are `0x01` +last two children' `TTag`s are `0xFE` and `0xFE` and their `STag`s are `0x01` and `0x00`, which means that they are both `CBiasing Branch Node`s. +# Reference Implementation + +In the Go programming language: + + - [RAC](https://godoc.org/github.com/google/wuffs/lib/rac) + - [RAC + Zlib](https://godoc.org/github.com/google/wuffs/lib/raczlib) + + # Acknowledgements I (Nigel Tao) thank Robert Obryk, Sanjay Ghemawat and Sean Klein for their