1 files changed, 75 insertions, 155 deletions
diff --git a/docs/en/cowboy/2.0/guide/modern_web/index.html b/docs/en/cowboy/2.0/guide/modern_web/index.html
index 69761906..26f1b213 100644
--- a/docs/en/cowboy/2.0/guide/modern_web/index.html
+++ b/docs/en/cowboy/2.0/guide/modern_web/index.html
@@ -69,153 +69,50 @@
 
 <h1 class="lined-header"><span>The modern Web</span></h1>
 
-<div class="paragraph"><p>Let&#8217;s take a look at various technologies from the beginnings
-of the Web up to this day, and get a preview of what&#8217;s
-coming next.</p></div>
-<div class="paragraph"><p>Cowboy is compatible with all the technology cited in this
-chapter except of course HTTP/2.0 which has no implementation
-in the wild at the time of writing.</p></div>
+<div class="paragraph"><p>Cowboy is a server for the modern Web. This chapter explains
+what it means and details all the standards involved.</p></div>
+<div class="paragraph"><p>Cowboy supports all the standards listed in this document.</p></div>
 <div class="sect1">
-<h2 id="_the_prehistoric_web">The prehistoric Web</h2>
+<h2 id="_http_2">HTTP/2</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>HTTP was initially created to serve HTML pages and only
-had the GET method for retrieving them. This initial
-version is documented and is sometimes called HTTP/0.9.
-HTTP/1.0 defined the GET, HEAD and POST methods, and
-was able to send data with POST requests.</p></div>
-<div class="paragraph"><p>HTTP/1.0 works in a very simple way. A TCP connection
-is first established to the server. Then a request is
-sent. Then the server sends a response back and closes
-the connection.</p></div>
-<div class="paragraph"><p>Suffice to say, HTTP/1.0 is not very efficient. Opening
-a TCP connection takes some time, and pages containing
-many assets load much slower than they could because of
-this.</p></div>
-<div class="paragraph"><p>Most improvements done in recent years focused on reducing
-this load time and reducing the latency of the requests.</p></div>
+<div class="paragraph"><p>HTTP/2 is the most efficient protocol for consuming Web
+services. It enables clients to keep a connection open
+for long periods of time; to send requests concurrently;
+to reduce the size of requests through HTTP headers
+compression; and more. The protocol is binary, greatly
+reducing the resources needed to parse it.</p></div>
+<div class="paragraph"><p>HTTP/2 also enables the server to push messages to the
+client. This can be used for various purposes, including
+the sending of related resources before the client requests
+them, in an effort to reduce latency. This can also be used
+to enable bidirectional communication.</p></div>
+<div class="paragraph"><p>Cowboy provides transparent support for HTTP/2. Clients
+that know it can use it; others fall back to HTTP/1.1
+automatically.</p></div>
+<div class="paragraph"><p>HTTP/2 is compatible with the HTTP/1.1 semantics.</p></div>
+<div class="paragraph"><p>HTTP/2 is defined by RFC 7540 and RFC 7541.</p></div>
 </div>
 </div>
 <div class="sect1">
 <h2 id="_http_1_1">HTTP/1.1</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>HTTP/1.1 quickly followed and added a keep-alive mechanism
-to allow using the same connection for many requests, as
-well as streaming capabilities, allowing an endpoint to send
-a body in well defined chunks.</p></div>
-<div class="paragraph"><p>HTTP/1.1 defines the OPTIONS, GET, HEAD, POST, PUT, DELETE,
-TRACE and CONNECT methods. The PATCH method was added in more
-recent years. It also improves the caching capabilities with
-the introduction of many headers.</p></div>
-<div class="paragraph"><p>HTTP/1.1 still works like HTTP/1.0 does, except the connection
-can be kept alive for subsequent requests. This however allows
-clients to perform what is called as pipelining: sending many
-requests in a row, and then processing the responses which will
-be received in the same order as the requests.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_rest">REST</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The design of HTTP/1.1 was influenced by the REST architectural
-style. REST, or REpresentational State Transfer, is a style of
-architecture for loosely connected distributed systems.</p></div>
-<div class="paragraph"><p>REST defines constraints that systems must obey to in order to
-be RESTful. A system which doesn&#8217;t follow all the constraints
-cannot be considered RESTful.</p></div>
-<div class="paragraph"><p>REST is a client-server architecture with a clean separation
-of concerns between the client and the server. They communicate
-by referencing resources. Resources can be identified, but
-also manipulated. A resource representation has a media type
-and information about whether it can be cached and how. Hypermedia
-determines how resources are related and how they can be used.
-REST is also stateless. All requests contain the complete
-information necessary to perform the action.</p></div>
-<div class="paragraph"><p>HTTP/1.1 defines all the methods, headers and semantics required
-to implement RESTful systems.</p></div>
-<div class="paragraph"><p>REST is most often used when designing web application APIs
-which are generally meant to be used by executable code directly.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_xmlhttprequest">XmlHttpRequest</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Also know as AJAX, this technology allows Javascript code running
-on a web page to perform asynchronous requests to the server.
-This is what started the move from static websites to dynamic
-web applications.</p></div>
-<div class="paragraph"><p>XmlHttpRequest still performs HTTP requests under the hood,
-and then waits for a response, but the Javascript code can
-continue to run until the response arrives. It will then receive
-the response through a callback previously defined.</p></div>
-<div class="paragraph"><p>This is of course still requests initiated by the client,
-the server still had no way of pushing data to the client
-on its own, so new technology appeared to allow that.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_long_polling">Long-polling</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Polling was a technique used to overcome the fact that the server
-cannot push data directly to the client. Therefore the client had
-to repeatedly create a connection, make a request, get a response,
-then try again a few seconds later. This is overly expensive and
-adds an additional delay before the client receives the data.</p></div>
-<div class="paragraph"><p>Polling was necessary to implement message queues and other
-similar mechanisms, where a user must be informed of something
-when it happens, rather than when he refreshes the page next.
-A typical example would be a chat application.</p></div>
-<div class="paragraph"><p>Long-polling was created to reduce the server load by creating
-less connections, but also to improve latency by getting the
-response back to the client as soon as it becomes available
-on the server.</p></div>
-<div class="paragraph"><p>Long-polling works in a similar manner to polling, except the
-request will not get a response immediately. Instead the server
-leaves it open until it has a response to send. After getting
-the response, the client creates a new request and gets back
-to waiting.</p></div>
-<div class="paragraph"><p>You probably guessed by now that long-polling is a hack, and
-like most hacks it can suffer from unforeseen issues, in this
-case it doesn&#8217;t always play well with proxies.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_html5">HTML5</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>HTML5 is, of course, the HTML version after HTML4. But HTML5
-emerged to solve a specific problem: dynamic web applications.</p></div>
-<div class="paragraph"><p>HTML was initially created to write web pages which compose
-a website. But soon people and companies wanted to use HTML
-to write more and more complex websites, eventually known as
-web applications. They are for example your news reader, your
-email client in the browser, or your video streaming website.</p></div>
-<div class="paragraph"><p>Because HTML wasn&#8217;t enough, they started using proprietary
-solutions, often implemented using plug-ins. This wasn&#8217;t
-perfect of course, but worked well enough for most people.</p></div>
-<div class="paragraph"><p>However, the needs for a standard solution eventually became
-apparent. The browser needed to be able to play media natively.
-It needed to be able to draw anything. It needed an efficient
-way of streaming events to the server, but also receiving
-events from the server.</p></div>
-<div class="paragraph"><p>The solution went on to become HTML5. At the time of writing
-it is being standardized.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_eventsource">EventSource</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>EventSource, sometimes also called Server-Sent Events, is a
-technology allowing servers to push data to HTML5 applications.</p></div>
-<div class="paragraph"><p>EventSource is one-way communication channel from the server
-to the client. The client has no means to talk to the server
-other than by using HTTP requests.</p></div>
-<div class="paragraph"><p>It consists of a Javascript object allowing setting up an
-EventSource connection to the server, and a very small protocol
-for sending events to the client on top of the HTTP/1.1
-connection.</p></div>
-<div class="paragraph"><p>EventSource is a lightweight solution that only works for
-UTF-8 encoded text data. Binary data and text data encoded
-differently are not allowed by the protocol. A heavier but
-more generic approach can be found in Websocket.</p></div>
+<div class="paragraph"><p>HTTP/1.1 is the previous version of the HTTP protocol.
+The protocol itself is text-based and suffers from numerous
+issues and limitations. In particular it is not possible
+to execute requests concurrently (though pipelining is
+sometimes possible), and it&#8217;s also sometimes difficult
+to detect that a client disconnected.</p></div>
+<div class="paragraph"><p>HTTP/1.1 does provide very good semantics for interacting
+with Web services. It defines the standard methods, headers
+and status codes used by HTTP/1.1 and HTTP/2 clients and
+servers.</p></div>
+<div class="paragraph"><p>HTTP/1.1 also defines compatibility with an older version
+of the protocol, HTTP/1.0, which was never really standardized
+across implementations.</p></div>
+<div class="paragraph"><p>The core of HTTP/1.1 is defined by RFC 7230, RFC 7231,
+RFC 7232, RFC 7233, RFC 7234 and RFC 7235. Numerous RFCs
+and other specifications exist defining additional HTTP
+methods, status codes, headers or semantics.</p></div>
 </div>
 </div>
 <div class="sect1">
@@ -235,25 +132,48 @@ alive.</p></div>
 <div class="paragraph"><p>A Websocket connection can be used to transfer any kind of data,
 small or big, text or binary. Because of this Websocket is
 sometimes used for communication between systems.</p></div>
+<div class="paragraph"><p>Websocket messages have no semantics on their own. Websocket
+is closer to TCP in that aspect, and requires you to design
+and implement your own protocol on top of it; or adapt an
+existing protocol to Websocket.</p></div>
+<div class="paragraph"><p>The Websocket protocol is defined by RFC 6455.</p></div>
 </div>
 </div>
 <div class="sect1">
-<h2 id="_http_2">HTTP/2</h2>
+<h2 id="_long_lived_requests">Long-lived requests</h2>
+<div class="sectionbody">
+<div class="paragraph"><p>Cowboy provides an interface that can be used to support
+long-polling or to stream large amounts of data reliably,
+including using Server-Sent Events.</p></div>
+<div class="paragraph"><p>Long-polling is a mechanism in which the client performs
+a request which may not be immediately answered by the
+server. It allows clients to request resources that may
+not currently exist, but are expected to be created soon,
+and which will be returned as soon as they are.</p></div>
+<div class="paragraph"><p>Long-polling is essentially a hack, but it is widely used
+to overcome limitations on older clients and servers.</p></div>
+<div class="paragraph"><p>Server-Sent Events is a small protocol defined as a media
+type, <code>text/event-stream</code>, along with a new HTTP header,
+<code>Last-Event-ID</code>. It is defined in the EventSource W3C
+specification.</p></div>
+<div class="paragraph"><p>Cowboy provides an interface known as loop handlers that
+facilitates the implementation of long-polling or stream
+mechanisms. It works regardless of the underlying protocol.</p></div>
+</div>
+</div>
+<div class="sect1">
+<h2 id="_rest">REST</h2>
 <div class="sectionbody">
-<div class="paragraph"><p>HTTP/2 is an attempt to reduce page loading time by opening a
-single connection per server, keeping it open for subsequent
-requests, and also by compressing the HTTP headers to reduce
-the size of requests.</p></div>
-<div class="paragraph"><p>HTTP/2 is compatible with HTTP/1.1 semantics, and is actually
-just a different way of performing HTTP requests and responses,
-by using binary frames instead of a text-based protocol.
-HTTP/2 also allows the server to send extra responses following
-a request. This is meant to allow sending the resources
-associated with the request before the client requests them,
-saving latency when loading websites.</p></div>
-<div class="paragraph"><p>Browsers make use of TLS Application-Layer Protocol Negotiation
-extension to upgrade to an HTTP/2 connection seamlessly if the
-server supports it.</p></div>
+<div class="paragraph"><p>REST, or REpresentational State Transfer, is a style of
+architecture for loosely connected distributed systems.
+It can easily be implemented on top of HTTP.</p></div>
+<div class="paragraph"><p>REST is essentially a set of constraints to be followed.
+Many of these constraints are purely architectural and
+solved by simply using HTTP. Some constraints must be
+explicitly followed by the developer.</p></div>
+<div class="paragraph"><p>Cowboy provides an interface known as REST handlers that
+simplifies the implementation of a REST API on top of
+the HTTP protocol.</p></div>
 </div>
 </div>