update "tahoe backup" docs, and webapi.txt's mkdir-with-children

diff --git a/docs/frontends/CLI.txt b/docs/frontends/CLI.txt
index 5f601f9d3610a50769f48c9dfa91002f86b61c11..e452924f41834f10fc20706ea556314b473dfab5 100644 (file)
--- a/docs/frontends/CLI.txt
+++ b/docs/frontends/CLI.txt
@@ -339,14 +339,17 @@ tahoe backup ~ work:backups
  underneath your "~" home directory, placing an immutable timestamped
  snapshot in e.g. work:backups/Archives/2009-02-06_04:00:05Z/ (note that the
  timestamp is in UTC, hence the "Z" suffix), and a link to the latest
- snapshot in work:backups/Latest/ . This command will use a small SQLite
- database known as the "backupdb", stored in
- ~/.tahoe/private/backupdb.sqlite, to remember which local files have been
- backed up already, and will avoid uploading files that have already been
- backed up. It compares timestamps and filesizes when making this comparison.
- The "tahoe backup" command also shares directories with the previous backup
- when nothing has changed, to run faster and to reduce the number of
- directories created.
+ snapshot in work:backups/Latest/ . This command uses a small SQLite database
+ known as the "backupdb", stored in ~/.tahoe/private/backupdb.sqlite, to
+ remember which local files have been backed up already, and will avoid
+ uploading files that have already been backed up. It compares timestamps and
+ filesizes when making this comparison. It also re-uses existing directories
+ which have identical contents. This lets it run faster and reduces the
+ number of directories created.
+
+ If you reconfigure your client node to switch to a different grid, you
+ should delete the stale backupdb.sqlite file, to force "tahoe backup" to
+ upload all files to the new grid.
 
 tahoe backup --exclude=*~ ~ work:backups
 

diff --git a/docs/frontends/webapi.txt b/docs/frontends/webapi.txt
index b43d836ca8941fc14688f9c488ca1b13e6aa82b5..91c2aa30732e7f73d69334f91f9b1a5f6b9673a4 100644 (file)
--- a/docs/frontends/webapi.txt
+++ b/docs/frontends/webapi.txt
@@ -359,12 +359,13 @@ POST /uri?t=mkdir-with-children
  Initial children are provided as the body of the POST form (this is more
  efficient than doing separate mkdir and set_children operations). If the
  body is empty, the new directory will be empty. If not empty, the body will
- be interpreted as a JSON-encoded dictionary of children with which the new
- directory should be populated, using the same format as would be returned in
- the 'children' value of the t=json GET request, described below. Each
- dictionary key should be a child name, and each value should be a list of
- [TYPE, PROPDICT], where PROPDICT contains "rw_uri", "ro_uri", and "metadata"
- keys (all others are ignored). For example, the PUT request body could be:
+ be interpreted as a UTF-8 JSON-encoded dictionary of children with which the
+ new directory should be populated, using the same format as would be
+ returned in the 'children' value of the t=json GET request, described below.
+ Each dictionary key should be a child name, and each value should be a list
+ of [TYPE, PROPDICT], where PROPDICT contains "rw_uri", "ro_uri", and
+ "metadata" keys (all others are ignored). For example, the PUT request body
+ could be:
 
   {
     "Fran\u00e7ais": [ "filenode", {
@@ -394,6 +395,11 @@ POST /uri?t=mkdir-with-children
  form submissions, since the body is not formatted this way. Doing so will
  cause a server error as the lower-level code misparses the request body.
 
+ Child file names should each be expressed as a unicode string, then used as
+ keys of the dictionary. The dictionary should then be converted into JSON,
+ and the resulting string encoded into UTF-8. This UTF-8 bytestring should
+ then be used as the POST body.
+
 POST /uri?t=mkdir-immutable
 
  Like t=mkdir-with-children above, but the new directory will be