Various fixes and tweaks to the user guide

8 files changed, 66 insertions, 29 deletions

diff --git a/doc/src/guide/book.asciidoc b/doc/src/guide/book.asciidoc
index 9c5f49e..3fdb3b7 100644
--- a/doc/src/guide/book.asciidoc
+++ b/doc/src/guide/book.asciidoc
@@ -21,16 +21,12 @@ include::introduction.asciidoc[Introduction]
 
 include::getting_started.asciidoc[Getting started]
 
-// NEW! Flow diagram here
-// MERGE include::overview.asciidoc[Request overview]
 include::flow_diagram.asciidoc[Flow diagram]
 
 = Configuration
 
 include::listeners.asciidoc[Listeners]
 
-include::streams.asciidoc[Streams]
-
 include::routing.asciidoc[Routing]
 
 include::constraints.asciidoc[Constraints]
@@ -69,19 +65,35 @@ include::resource_design.asciidoc[Designing a resource handler]
 
 include::ws_protocol.asciidoc[The Websocket protocol]
 
-include::ws_handlers.asciidoc[Handling Websocket connections]
+include::ws_handlers.asciidoc[Websocket handlers]
 
-= Internals
+= Advanced
 
-// TODO: shouldn't be needed anymore?
-include::architecture.asciidoc[Architecture]
-
-// TODO: Move into Common scenarios or something; switch to streams
-include::broken_clients.asciidoc[Dealing with broken clients]
+include::streams.asciidoc[Streams]
 
 include::middlewares.asciidoc[Middlewares]
 
+// @todo Rather have two chapters, custom handlers and custom protocol upgrades
 include::sub_protocols.asciidoc[Sub protocols]
 
-// TODO: they're gone
+//= Additional information
+
+//include::migrating_from_1.0.asciidoc[Migrating from Cowboy 1.0 to 2.0]
+
+// @todo Maybe history? Could take info from architecture also.
+
+= Deprecated chapters
+
+== About the deprecated chapters
+
+The following chapters were relevant in Cowboy 1.0. They have
+not been updated for Cowboy 2.0 yet. The information in these
+chapters may or may not be useful.
+
+include::architecture.asciidoc[Architecture]
+
+include::broken_clients.asciidoc[Dealing with broken clients]
+
 include::hooks.asciidoc[Hooks]
+
+include::overview.asciidoc[Overview]
diff --git a/doc/src/guide/flow_diagram.asciidoc b/doc/src/guide/flow_diagram.asciidoc
index 1095404..ad2110d 100644
--- a/doc/src/guide/flow_diagram.asciidoc
+++ b/doc/src/guide/flow_diagram.asciidoc
@@ -2,3 +2,11 @@
 == Flow diagram
 
 Placeholder chapter.
+
+Cowboy 2.0 has changed the request flow and general architecture.
+You can read about the Cowboy 1.0 architecture and flow here:
+
+* xref:architecture[Architecture]
+* xref:overview[Overview]
+
+This chapter will be updated in a future pre-release.
diff --git a/doc/src/guide/handlers.asciidoc b/doc/src/guide/handlers.asciidoc
index 88fbc21..e073dfb 100644
--- a/doc/src/guide/handlers.asciidoc
+++ b/doc/src/guide/handlers.asciidoc
@@ -29,9 +29,9 @@ We need to use the Req object to reply.
 [source,erlang]
 ----
 init(Req0, State) ->
-    Req = cowboy_req:reply(200, [
-        {<<"content-type">>, <<"text/plain">>}
-    ], <<"Hello World!">>, Req0),
+    Req = cowboy_req:reply(200, #{
+        <<"content-type">> => <<"text/plain">>
+    }, <<"Hello World!">>, Req0),
     {ok, Req, State}.
 ----
 
@@ -81,8 +81,7 @@ xref:sub_protocols[Sub protocols] chapter.
 
 === Cleaning up
 
-With the exception of Websocket handlers, all handler types
-provide the optional `terminate/3` callback.
+All handler types provide the optional `terminate/3` callback.
 
 [source,erlang]
 ----
diff --git a/doc/src/guide/listeners.asciidoc b/doc/src/guide/listeners.asciidoc
index 901b922..7d5faec 100644
--- a/doc/src/guide/listeners.asciidoc
+++ b/doc/src/guide/listeners.asciidoc
@@ -7,7 +7,7 @@ Depending on the connection handshake, one or another protocol
 may be used.
 
 This chapter is specific to Cowboy. Please refer to the
-http://ninenines.eu/docs/en/ranch/1.2/guide/listeners/[Ranch User Guide]
+http://ninenines.eu/docs/en/ranch/1.3/guide/listeners/[Ranch User Guide]
 for more information about listeners.
 
 Cowboy provides two types of listeners: one listening for
diff --git a/doc/src/guide/loop_handlers.asciidoc b/doc/src/guide/loop_handlers.asciidoc
index c0195ea..2c82c53 100644
--- a/doc/src/guide/loop_handlers.asciidoc
+++ b/doc/src/guide/loop_handlers.asciidoc
@@ -16,7 +16,7 @@ most known example of such practice is known as long polling.
 Loop handlers can also be used for requests where a response is
 partially available and you need to stream the response body
 while the connection is open. The most known example of such
-practice is known as server-sent events.
+practice is server-sent events.
 
 While the same can be accomplished using plain HTTP handlers,
 it is recommended to use loop handlers because they are well-tested
@@ -66,7 +66,7 @@ message otherwise.
 [source,erlang]
 ----
 info({reply, Body}, Req, State) ->
-    cowboy_req:reply(200, [], Body, Req),
+    cowboy_req:reply(200, #{}, Body, Req),
     {stop, Req, State};
 info(_Msg, Req, State) ->
     {ok, Req, State, hibernate}.
@@ -96,19 +96,19 @@ This can be done by initiating a chunked reply in the
 every time a message is received.
 
 The following snippet does exactly that. As you can see
-a chunk is sent every time a `chunk` message is received,
+a chunk is sent every time an `event` message is received,
 and the loop is stopped by sending an `eof` message.
 
 [source,erlang]
 ----
 init(Req, State) ->
-    Req2 = cowboy_req:chunked_reply(200, [], Req),
+    Req2 = cowboy_req:stream_reply(200, Req),
     {cowboy_loop, Req2, State}.
 
 info(eof, Req, State) ->
     {stop, Req, State};
-info({chunk, Chunk}, Req, State) ->
-    cowboy_req:chunk(Chunk, Req),
+info({event, Data}, Req, State) ->
+    cowboy_req:stream_body(Data, nofin, Req),
     {ok, Req, State};
 info(_Msg, Req, State) ->
     {ok, Req, State}.
@@ -125,6 +125,9 @@ for general instructions about cleaning up.
 
 === Timeout
 
+Note that this feature currently does not work. It will be
+brought back in a future 2.0 pre-release.
+
 By default Cowboy will not attempt to close the connection
 if there is no activity from the client. This is not always
 desirable, which is why you can set a timeout. Cowboy will
diff --git a/doc/src/guide/multipart.asciidoc b/doc/src/guide/multipart.asciidoc
index 630b210..77d263a 100644
--- a/doc/src/guide/multipart.asciidoc
+++ b/doc/src/guide/multipart.asciidoc
@@ -146,7 +146,7 @@ all bodies:
 [source,erlang]
 ----
 multipart(Req0) ->
-    case cowboy_req:part(Req0) of
+    case cowboy_req:read_part(Req0) of
         {ok, _Headers, Req} ->
             multipart(Req);
         {done, Req} ->
diff --git a/doc/src/guide/rest_handlers.asciidoc b/doc/src/guide/rest_handlers.asciidoc
index 748fca4..c69f02b 100644
--- a/doc/src/guide/rest_handlers.asciidoc
+++ b/doc/src/guide/rest_handlers.asciidoc
@@ -101,13 +101,13 @@ and in the second case that we send one as HTML.
 
 === Meta data
 
-Cowboy will set informative meta values at various points of the
-execution. You can retrieve them using `cowboy_req:meta/{2,3}`.
-The values are defined in the following table.
+Cowboy will set informative values to the Req object at various
+points of the execution. You can retrieve them by matching the
+Req object directly. The values are defined in the following table:
 
 [cols="<,<",options="header"]
 |===
-| Meta key   | Details
+| Key        | Details
 | media_type | The content-type negotiated for the response entity.
 | language   | The language negotiated for the response entity.
 | charset    | The charset negotiated for the response entity.
diff --git a/doc/src/guide/streams.asciidoc b/doc/src/guide/streams.asciidoc
new file mode 100644
index 0000000..243e581
--- /dev/null
+++ b/doc/src/guide/streams.asciidoc
@@ -0,0 +1,15 @@
+[[streams]]
+== Streams
+
+Placeholder chapter.
+
+Streams are a new feature in Cowboy 2.0 that requires
+a little more tweaking before they can be generally
+useful. This chapter will be made available in a future
+pre-release.
+
+Streams are meant to replace hooks. The relevant chapters
+for Cowboy 1.0 were:
+
+* xref:hooks[Hooks]
+* xref:broken_clients[Dealing with broken clients]