From f75a10a23000700aeb5799f67b592a5ea881fada Mon Sep 17 00:00:00 2001 From: Nigel Tao Date: Sat, 24 Aug 2019 15:41:35 +1000 Subject: [PATCH] Add "random access" definition to ractool docs --- cmd/ractool/data.go | 16 +++++++++++++++- cmd/ractool/gen.go | 6 +++--- cmd/ractool/main.go | 9 +++++++++ 3 files changed, 27 insertions(+), 4 deletions(-) diff --git a/cmd/ractool/data.go b/cmd/ractool/data.go index 0e4ce762..9954b8f2 100644 --- a/cmd/ractool/data.go +++ b/cmd/ractool/data.go @@ -16,7 +16,21 @@ package main -const usageStr = `Usage: +const usageStr = `ractool manipulates Random Access Compression (RAC) files. + +Random access means that it is possible to reconstruct part of the decompressed +file, starting at a given offset into the decompressed file, without always +having to first decompress all of the preceding data. + +In comparison to some other popular compression formats, all three of the Zlib, +Brotli and Zstandard specifications (RFCs 1950, 7932 and 8478) explicitly +contain the identical phrase: "the data format defined by this specification +does not attempt to allow random access to compressed data". + +See the RAC specification for more details: +https://github.com/google/wuffs/blob/master/doc/spec/rac-spec.md + +Usage: ractool [flags] [input_filename] diff --git a/cmd/ractool/gen.go b/cmd/ractool/gen.go index fe9fd626..ba8ae205 100644 --- a/cmd/ractool/gen.go +++ b/cmd/ractool/gen.go @@ -41,13 +41,13 @@ func main1() error { return err } - if i := bytes.Index(src, []byte("Usage:\n\n")); i < 0 { - return fmt.Errorf(`couldn't find "Usage" sub-string`) + if i := bytes.Index(src, []byte("ractool manipulates ")); i < 0 { + return fmt.Errorf(`couldn't find documentation sub-string`) } else { src = src[i:] } if j := bytes.Index(src, []byte("*/")); j < 0 { - return fmt.Errorf(`couldn't find "Usage" sub-string`) + return fmt.Errorf(`couldn't find documentation sub-string`) } else { src = src[:j] } diff --git a/cmd/ractool/main.go b/cmd/ractool/main.go index 44b01685..593ae2e2 100644 --- a/cmd/ractool/main.go +++ b/cmd/ractool/main.go @@ -19,6 +19,15 @@ /* ractool manipulates Random Access Compression (RAC) files. +Random access means that it is possible to reconstruct part of the decompressed +file, starting at a given offset into the decompressed file, without always +having to first decompress all of the preceding data. + +In comparison to some other popular compression formats, all three of the Zlib, +Brotli and Zstandard specifications (RFCs 1950, 7932 and 8478) explicitly +contain the identical phrase: "the data format defined by this specification +does not attempt to allow random access to compressed data". + See the RAC specification for more details: https://github.com/google/wuffs/blob/master/doc/spec/rac-spec.md