Corrections and clarifications of REST API Spec

[TallTed]

Some markup and language tweaks for better reader clarity; some punctuation fixes for typos.

Significant changes to the OPTIONS method section which did not conform to RFC 7231 --
https://tools.ietf.org/html/rfc7231#section-4.3.7 -- as the example was for the specific /data/ container, but the description was server-wide.

[dmitrizagidulin]

Thanks, @TallTed! Good work.

My only question is - let's make sure that OPTIONS * actually works on node-solid-server; that might not be implemented or supported :)

[TallTed]

@dmitrizagidulin - I quite believe that OPTIONS * as in HTTP RFC 7231 section 4.3.7 "Request Methods -- Method Definitions -- OPTIONS" and 7230 section 5.3.4 "Message Routing -- Request Target -- asterisk-form" may not (yet) be implemented or supported in node-solid-server, given that the SoLiD API spec was not in such conformance on this point.

I think such lack should be considered a defect in node-solid-server, and not block correction of the SoLiD API spec, as the HTTP RFCs are prerequisites and thus take precedence over the dependent works.

[dmitrizagidulin]

Sounds good. If you can, open an issue on node-solid-server to implement OPTIONS *. I agree that the spec should include it.

[pfriedman]

These look like appropriate changes making file read better.

[TallTed]

@RubenVerborgh @kjetilk @dmitrizagidulin @elf-pavlik
(in other words, all previous committers)

Conflicts from intervening changes resolved. Whoever can, please merge...

[TallTed]

Again...

@RubenVerborgh @kjetilk @dmitrizagidulin @elf-pavlik
(in other words, all previous committers)

Conflicts from more intervening changes resolved. Whomever can, please merge...

[TallTed]

Apparently needs new reviews, since conflict re-resolution...

@pfriedman @dmitrizagidulin @gobengo were positive last round.

[kjetilk]

Right, so, I don't see anything wrong with it, but also note that these documents needs reworking entirely.

[TallTed]

@kjetilk - Understood, about the full rework. I think applying this relatively small adjustment before that full rework will result in a better end than leaving it out until after, at which point the rework may itself be broken because this error persists...