Update docs for PUT attachments

[flimzy]

These headers were completely misdocumented, even for Couch 1.6. But
they've all been removed entirely for Couch 2.0.0, according to my testing.

[nickva]

Thanks for taking a look. In this case I wanted to check because wasn't sure. I still see those headers as valid thought. Here is how I tested:

(Used latest master, then python-couchdb in ipython prompt and httpie command line tool)

In [22]: db
Out[22]: <Database u'db'>

In [27]: db.put_attachment(d1, 'tttttttttttttttttttttttttttttttttttttttttttt', 't1', content_type='text/plain')

In [28]: db.put_attachment(d1, 'tttttttttttttttttttttttttttttttttttttttttttt', 'b1', content_type='application/blah')

Created a db db and doc d1. Then created two attachments: one with a text/plain and another with application/blah mime types. The text/plain is special because in config options we specify that it can be compressed

[attachments]
compression_level = 8 ; from 1 (lowest, fastest) to 9 (highest, slowest), 0 to disable compression
compressible_types = text/*, application/javascript, application/json, application/xml

Listing the attachments we see that text/* one we get the Content-Encoding and the Content-Length as compressed values. But interestingly (but not surprising) we can't do Accept-Range requests for it.

~/asf (master)$ http http://adm:pass@localhost:15984/db/d1/t1
HTTP/1.1 200 OK
Accept-Ranges: none
Cache-Control: must-revalidate
Content-Encoding: gzip
Content-Length: 24
Content-MD5: L5mFG13zKQUGqeARUOwUkQ==
Content-Type: text/plain
Date: Tue, 04 Apr 2017 02:59:27 GMT
ETag: "L5mFG13zKQUGqeARUOwUkQ=="
Server: CouchDB/2.0.0-b9e7e12 (Erlang OTP/19)

tttttttttttttttttttttttttttttttttttttttttttt

~/asf (master)$ http http://adm:pass@localhost:15984/db/d1/b1
HTTP/1.1 200 OK
Accept-Ranges: bytes
Cache-Control: must-revalidate
Content-Length: 44
Content-MD5: 52wzeuub4aG8rDtYd947mA==
Content-Type: application/blah
Date: Tue, 04 Apr 2017 03:02:34 GMT
ETag: "52wzeuub4aG8rDtYd947mA=="
Server: CouchDB/2.0.0-b9e7e12 (Erlang OTP/19)

tttttttttttttttttttttttttttttttttttttttttttt

[flimzy]

You're right. I modified the wrong headers. I meant to update the PUT description not HEAD. Updated.

[flimzy]

I'd also love to update this for the 1.6 docs. Do we have a way to update historical documentation?

[nickva]

@flimzy

Ah I see. To be fair, I noticed, I messed up as well as I didn't check HEAD, only GET.

Yeah I imagine Accept-Ranges might not apply to PUT but will need to verify it.

As for 1.6 try to checkout 1.6.x branch then look in share/doc folder. I imagine making a PR then to that 1.6.x branch. But I am not too familiar with that process there TBH.

@wohali, you did some documentation work, do you have any guidance on updating 1.6.x documentation and how it differs from 2.0

[flimzy]

From RFC 7233, 3.1:

A server MUST ignore a Range header field received with a request method other than GET.

By extension, it seems logical that advertising Accept-Ranges for anything other than GET (and by extension, HEAD), doesn't make sense.

[nickva]

Good find!

[nickva]

+1

Thank you!