Enhance ext/zonefile/README.md to describe the currently available

functionality.

FossilOrigin-Name: 100137c7f68b2d9a329d6d43e6c0a81b6ac843678b670ab6cce5f510bc58b7a8

diff --git a/ext/zonefile/README.md b/ext/zonefile/README.md
index d70b07e8358c5dce9b9d55c790282d5555add257..ac79d3e1de227556dd9792d120f74a14387b3ebb 100644 (file)
--- a/ext/zonefile/README.md
+++ b/ext/zonefile/README.md
@@ -1,5 +1,93 @@
 
-Notes:
+# The Zonefile Extension
+
+## Functionality
+
+### Creating Zonefile Files
+
+To create a new zonefile, first create a database table with the following
+schema:
+
+>     CREATE TABLE data(
+>       k INTEGER PRIMARY KEY,
+>       frame INTEGER DEFAULT -1,   -- frame number.  Automatic if -1
+>       idx INTEGER DEFAULT -1,     -- index of entry within frame.  Auto if -1
+>       v BLOB
+>     );
+
+The table may be created in a persistent or temporary database and may
+take any name, but must contain the columns above. The table must be 
+populated with a row for each key intended to appear in the new zonefile
+file.
+
+Once the table is populated, a zonefile is created using the following
+SQL:
+
+>     SELECT zonefile_write(<file>, <table> [, <parameters>]);
+
+where &lt;file&gt; is the name of the file to create on disk, &lt;table&gt; 
+is the name of the database table to read and optional argument 
+&lt;parameters&gt; is a JSON object containing various attributes that
+influence creation of the zonefile file. 
+
+Currently the only &lt;parameters&gt; attribute supported is 
+<i>maxAutoFrameSize</i>, which sets the maximum frame size in bytes for
+automatically generated zonefile frames. 
+
+For example, to create a zonefile named "test.zonefile" based on the
+contents of database table "test_input" and with a maximum automatic
+frame size of 4096 bytes:
+
+>     SELECT zonefile_write('test.zonefile', 'test_input',
+>       '{"maxAutoFrameSize":4096}'
+>     );
+
+### Using (Reading) Zonefile Files
+
+To create a new zonefile table:
+
+>     CREATE VIRTUAL TABLE z1 USING zonefile;
+
+This creates two virtual tables in the database schema. One read-only table
+named "z1", with a schema equivalent to:
+
+>     CREATE TABLE z1(  -- this whole table is read-only
+>       k INTEGER PRIMARY KEY,
+>       v BLOB,
+>       fileid INTEGER,
+>       frame INTEGER,
+>       ofst INTEGER,
+>       sz INTEGER
+>     );
+
+And a read-write table named "z1_files" with a schema like:
+
+>     CREATE TABLE z1_files(
+>       filename TEXT PRIMARY KEY,
+>       ekey BLOB,         -- encryption key
+>       fileid INTEGER,    -- read-only
+>       header JSON HIDDEN -- read-only
+>     );
+
+Both tables are initially empty. To add a zonefile to the index, insert a
+row into the "z1_files" table:
+
+>     INSERT INTO z1_files(filename) VALUES(<filename>);
+
+Currently, any value provided for any column other than "filename" is 
+ignored. Files are removed from the index by deleting rows from the
+z1_files table:
+
+>     DELETE FROM z1_files WHERE filename = <filename>;
+
+Once zonefile files have been added to the index, their contents are 
+visible in table "z1". To retrieve the value associated with a single
+key from one of the zonefile files in the index:
+
+>     SELECT v FROM z1 WHERE k = <key>;
+
+
+## Notes
 
   *  Contrary to the spec, the implementation uses 32-bit (not 16-bit) frame
      numbers. So the KeyOffsetPair structure becomes:
@@ -22,6 +110,6 @@ Notes:
      necessary as we may not know the offset of the start of the frame data
      until after the ZoneFileIndex structure is compressed.
 
-  *  Currently there is no support for encryption or compression.
+  *  Currently there is no support at all for encryption or compression.
 
 

diff --git a/manifest b/manifest
index 4fa25bd68147336a3e7e6e912a2a60e629267148..22ad5f1504ef0cdec1f5d89b3d33dd161cb1e31d 100644 (file)
--- a/manifest
+++ b/manifest
@@ -1,5 +1,5 @@
-C Remove,\sfor\snow,\sthe\s"priority"\scolumn\sfrom\sthe\szonefile_files\svirtual\stable.
-D 2018-02-13T18:02:00.303
+C Enhance\sext/zonefile/README.md\sto\sdescribe\sthe\scurrently\savailable\nfunctionality.
+D 2018-02-13T19:01:08.333
 F .fossil-settings/empty-dirs dbb81e8fc0401ac46a1491ab34a7f2c7c0452f2f06b54ebb845d024ca8283ef1
 F .fossil-settings/ignore-glob 35175cdfcf539b2318cb04a9901442804be81cd677d8b889fcc9149c21f239ea
 F Makefile.in 7a3f714b4fcf793108042b7b0a5c720b0b310ec84314d61ba7f3f49f27e550ea
@@ -408,7 +408,7 @@ F ext/session/test_session.c eb0bd6c1ea791c1d66ee4ef94c16500dad936386
 F ext/userauth/sqlite3userauth.h 7f3ea8c4686db8e40b0a0e7a8e0b00fac13aa7a3
 F ext/userauth/user-auth.txt e6641021a9210364665fe625d067617d03f27b04
 F ext/userauth/userauth.c 3410be31283abba70255d71fd24734e017a4497f
-F ext/zonefile/README.md 1b5c62cad3ec25d48b28f2550d390768fdfef6d088ff9db8af676ab64f6c4530
+F ext/zonefile/README.md fd8039cb0b421059ef90d014b4d71a1e376cb7d1210e80a896d76908708669e4
 F ext/zonefile/zonefile.c 212c9a8778759c292685a0915ff5bcbdb9d279c2fe791021572617971c896c5b
 F ext/zonefile/zonefile1.test 8904658bd8332dc0d0c77c0c74c9c83dce4123a442bb971d5baf00170f6d0afe
 F install-sh 9d4de14ab9fb0facae2f48780b874848cbf2f895 x
@@ -1708,7 +1708,7 @@ F vsixtest/vsixtest.tcl 6a9a6ab600c25a91a7acc6293828957a386a8a93
 F vsixtest/vsixtest.vcxproj.data 2ed517e100c66dc455b492e1a33350c1b20fbcdc
 F vsixtest/vsixtest.vcxproj.filters 37e51ffedcdb064aad6ff33b6148725226cd608e
 F vsixtest/vsixtest_TemporaryKey.pfx e5b1b036facdb453873e7084e1cae9102ccc67a0
-P fdb6c0c5dc5a67ca16dfafc6e677f73936f36e357a2ff288b4958ddee0544603
-R 7ee10389f1633a4ccc7da396851ded16
+P 8bf5154bc6e31e206931d97c743eadaba4ef938c11e006082d795439dadaeb8f
+R ac88557d5661bd1ac981fca2d5815858
 U dan
-Z 0a6dede478fe88813cd34fe2d513e5c6
+Z 857bf6fa80777d961d06ea17c5dbe1b2

diff --git a/manifest.uuid b/manifest.uuid
index 27cdec9c1838c284dacd0a088d7f90eeb5e6a950..994eb4acdd3b5ca7272502b54a160742c3b5b167 100644 (file)
--- a/manifest.uuid
+++ b/manifest.uuid
@@ -1 +1 @@
-8bf5154bc6e31e206931d97c743eadaba4ef938c11e006082d795439dadaeb8f
\ No newline at end of file
+100137c7f68b2d9a329d6d43e6c0a81b6ac843678b670ab6cce5f510bc58b7a8
\ No newline at end of file