From c582a21e998881c33d2cfa641cccaf483251ff34 Mon Sep 17 00:00:00 2001
From: Brian Warner <warner@lothar.com>
Date: Fri, 22 Apr 2016 19:23:49 -0700
Subject: [PATCH] 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.
---
 docs/frontends/webapi.rst | 55 +++++++++++++++++++--------------------
 1 file changed, 27 insertions(+), 28 deletions(-)

diff --git a/docs/frontends/webapi.rst b/docs/frontends/webapi.rst
index 1ecebfded..8df706f14 100644
--- a/docs/frontends/webapi.rst
+++ b/docs/frontends/webapi.rst
@@ -1040,43 +1040,42 @@ Viewing/Downloading a File
 
 ``GET /uri/$DIRCAP/[SUBDIRS../]FILENAME``
 
- This 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.
+ These will retrieve the contents of the given file. The HTTP response body
+ will contain the sequence of bytes that make up the file.
+
+ 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..
+ 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 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.
 
-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.
+ 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.
 
 
 Getting Information About a File Or Directory (as HTML)