Changeset c582a21 in trunk

Timestamp:

2016-04-23T02:23:49Z (9 years ago)

Author:

Brian Warner <warner@…>

Branches:

master

Children:

afb7718

Parents:

3e73461

Message:

webapi.rst: fixups

Re-indent the blocks for consistency, improve the explanation of
?filename=foo.jpg to match it's new location, use new-style reference
for urls-and-utf8 footnote.

File:

• docs/frontends/webapi.rst (modified) (1 diff)

docs/frontends/webapi.rst ¶

@@ -1041 +1041 @@
 ``GET /uri/$DIRCAP/[SUBDIRS../]FILENAME``
 
- This will retrieve the contents of the given file. The HTTP response body
+``GET /named/$FILECAP/FILENAME``
+
+ These will retrieve the contents of the given file. The HTTP response body
  will contain the sequence of bytes that make up the file.
 
-``GET /named/$FILECAP/FILENAME``
-
- This is an alternate download form which makes it easier to get the correct
- filename. The Tahoe server will provide the contents of the given file, with
- a Content-Type header derived from the given filename. This form is used to
- get browsers to use the "Save Link As" feature correctly, and also helps
- command-line tools like "wget" and "curl" use the right filename. Note that
- this form can *only* be used with file caps; it is an error to use a
- directory cap after the /named/ prefix.
+ The ``/named/`` form is an alternative to ``/uri/$FILECAP`` which makes it
+ easier to get the correct filename. The Tahoe server will provide the
+ contents of the given file, with a Content-Type header derived from the
+ given filename. This form is used to get browsers to use the "Save Link As"
+ feature correctly, and also helps command-line tools like "wget" and "curl"
+ use the right filename. Note that this form can *only* be used with file
+ caps; it is an error to use a directory cap after the /named/ prefix.
 
  URLs may also use /file/$FILECAP/FILENAME as a synonym for
  /named/$FILECAP/FILENAME. The use of "/file/" is deprecated in favor of
  "/named/" and support for "/file/" will be removed in a future release of
- Tahoe-LAFS..
-
-
-If you want the HTTP response to include a useful Content-Type header, either
-use the second or third form or add a "filename=foo" query argument, like
-"GET /uri/$FILECAP?filename=foo.jpg".  The bare "GET /uri/$FILECAP" does not
-give the Tahoe node enough information to determine a Content-Type (since
-LAFS immutable files are merely sequences of bytes, not typed and named file
-objects).
-
-If the URL has both filename= and "save=true" in the query arguments, then
-the server to add a "Content-Disposition: attachment" header, along with a
-filename= parameter. When a user clicks on such a link, most browsers will
-offer to let the user save the file instead of displaying it inline (indeed,
-most browsers will refuse to display it inline). "true", "t", "1", and other
-case-insensitive equivalents are all treated the same.
-
-Character-set handling in URLs and HTTP headers is a dubious art [1]_. For
-maximum compatibility, Tahoe simply copies the bytes from the filename=
-argument into the Content-Disposition header's filename= parameter, without
-trying to interpret them in any particular way.
+ Tahoe-LAFS.
+
+ If you use the first form (``/uri/$FILECAP``) and want the HTTP response to
+ include a useful Content-Type header, add a "filename=foo" query argument,
+ like "GET /uri/$FILECAP?filename=foo.jpg". The bare "GET /uri/$FILECAP" does
+ not give the Tahoe node enough information to determine a Content-Type
+ (since LAFS immutable files are merely sequences of bytes, not typed and
+ named file objects).
+
+ If the URL has both filename= and "save=true" in the query arguments, then
+ the server to add a "Content-Disposition: attachment" header, along with a
+ filename= parameter. When a user clicks on such a link, most browsers will
+ offer to let the user save the file instead of displaying it inline (indeed,
+ most browsers will refuse to display it inline). "true", "t", "1", and other
+ case-insensitive equivalents are all treated the same.
+
+ Character-set handling in URLs and HTTP headers is a :ref:`dubious
+ art<urls-and-utf8>`. For maximum compatibility, Tahoe simply copies the
+ bytes from the filename= argument into the Content-Disposition header's
+ filename= parameter, without trying to interpret them in any particular way.