docs: amend configuration, webapi documentation to talk about MDMF

docs/configuration.rst

@@ -326,6 +326,23 @@ Client Configuration
     (Mutable files use a different share placement algorithm that does not
     currently consider this parameter.)
 
+``mutable.format = sdmf or mdmf``
+
+    This value tells Tahoe-LAFS what the default mutable file format should
+    be. If ``mutable.format=sdmf``, then newly created mutable files will be
+    in the old SDMF format. This is desirable for clients that operate on
+    grids where some peers run older versions of Tahoe-LAFS, as these older
+    versions cannot read the new MDMF mutable file format. If
+    ``mutable.format`` is ``mdmf``, then newly created mutable files will use
+    the new MDMF format, which supports efficient in-place modification and
+    streaming downloads. You can overwrite this value using a special
+    mutable-type parameter in the webapi. If you do not specify a value here,
+    Tahoe-LAFS will use SDMF for all newly-created mutable files.
+
+    Note that this parameter only applies to mutable files. Mutable
+    directories, which are stored as mutable files, are not controlled by
+    this parameter and will always use SDMF. We may revisit this decision
+    in future versions of Tahoe-LAFS.
 
 Frontend Configuration
 ======================

docs/frontends/webapi.rst

@@ -365,10 +365,17 @@ Writing/Uploading A File
  To use the /uri/$FILECAP form, $FILECAP must be a write-cap for a mutable file.
 
  In the /uri/$DIRCAP/[SUBDIRS../]FILENAME form, if the target file is a
- writeable mutable file, that file's contents will be overwritten in-place. If
- it is a read-cap for a mutable file, an error will occur. If it is an
- immutable file, the old file will be discarded, and a new one will be put in
- its place.
+ writeable mutable file, that file's contents will be overwritten
+ in-place. If it is a read-cap for a mutable file, an error will occur.
+ If it is an immutable file, the old file will be discarded, and a new
+ one will be put in its place. If the target file is a writable mutable
+ file, you may also specify an "offset" parameter -- a byte offset that
+ determines where in the mutable file the data from the HTTP request
+ body is placed. This operation is relatively efficient for MDMF mutable
+ files, and is relatively inefficient (but still supported) for SDMF
+ mutable files. If no offset parameter is specified, then the entire
+ file is replaced with the data from the HTTP request body. For an
+ immutable file, the "offset" parameter is not valid.
 
  When creating a new file, if "mutable=true" is in the query arguments, the
  operation will create a mutable file instead of an immutable one.
@@ -389,7 +396,16 @@ Writing/Uploading A File
 
  If "mutable=true" is in the query arguments, the operation will create a
  mutable file, and return its write-cap in the HTTP respose. The default is
- to create an immutable file, returning the read-cap as a response.
+ to create an immutable file, returning the read-cap as a response. If
+ you create a mutable file, you can also use the "mutable-type" query
+ parameter. If "mutable-type=sdmf", then the mutable file will be created
+ in the old SDMF mutable file format. This is desirable for files that
+ need to be read by old clients. If "mutable-type=mdmf", then the file
+ will be created in the new MDMF mutable file format. MDMF mutable files
+ can be downloaded more efficiently, and modified in-place efficiently,
+ but are not compatible with older versions of Tahoe-LAFS. If no
+ "mutable-type" argument is given, the file is created in whatever
+ format was configured in tahoe.cfg.
 
 
 Creating A New Directory
@@ -1082,7 +1098,13 @@ Uploading a File
  If a "mutable=true" argument is provided, the operation will create a
  mutable file, and the response body will contain the write-cap instead of
  the upload results page. The default is to create an immutable file,
- returning the upload results page as a response.
+ returning the upload results page as a response. If you create a
+ mutable file, you may choose to specify the format of that mutable file
+ with the "mutable-type" parameter. If "mutable-type=mdmf", then the
+ file will be created as an MDMF mutable file. If "mutable-type=sdmf",
+ then the file will be created as an SDMF mutable file. If no value is
+ specified, the file will be created in whatever format is specified in
+ tahoe.cfg.
 
 
 ``POST /uri/$DIRCAP/[SUBDIRS../]?t=upload``