Add documentation for generating zdicts

Signed-off-by: Jonathan Dieter <jdieter@gmail.com>

diff --git a/README.md b/README.md
index 379ebe0431509f768e61697c3fe12b85b567a346..9244aa4b922e817b94ae029ae84a49d334e4b5af 100644 (file)
--- a/README.md
+++ b/README.md
@@ -50,6 +50,37 @@ To read a zchunk header, run:
 zck_read_header <file>
 ```
 
+
+## Zchunk dictionaries
+
+If you're creating a zchunk file that has any repetitive data, you may be
+able to reduce the file size by using a [zstd dictionary](https://facebook.github.io/zstd/#small-data).
+The dictionary is stored as extra data in chunk 0, but is used as a starting
+point for compressing each chunk, which can give a significant overall savings.
+
+It is important that all further revisions of the zchunk file use the same
+dictionary.  If the dictionary changes, none of the chunks will match from the
+old file, and the full new file will be downloaded.
+
+Zchunk can use any zstd dictionary, but also includes a utility to generate the
+ideal zstd dictionary for a zchunk file.
+
+To create an ideal dictionary for a zchunk file, run:
+```
+zck_gen_zdict <file.zck>
+```
+
+The dictionary will be saved as `<file.zdict>`.
+
+You will then need to recompress the file with the dictionary:
+```
+zck -D <uncompressed file>
+```
+
+Note that `zck_gen_zdict` does require that the `zstd` binary be installed on
+your system.
+
+
 ## Documentation
 - [Format definition](zchunk_format.txt)
 - [Initial announcement](https://www.jdieter.net/posts/2018/04/30/introducing-zchunk)