Rebuild using Asciideck

1 files changed, 65 insertions, 106 deletions

diff --git a/docs/en/cowboy/2.4/guide/cookies/index.html b/docs/en/cowboy/2.4/guide/cookies/index.html
index d9df673a..3ef48485 100644
--- a/docs/en/cowboy/2.4/guide/cookies/index.html
+++ b/docs/en/cowboy/2.4/guide/cookies/index.html
@@ -62,144 +62,103 @@
 
 <h1 class="lined-header"><span>Using cookies</span></h1>
 
-<div class="paragraph"><p>Cookies are a mechanism allowing applications to maintain
-state on top of the stateless HTTP protocol.</p></div>
-<div class="paragraph"><p>Cookies are a name/value store where the names and values are
-stored in plain text. They expire either after a delay
-or when the browser closes. They can be configured on a
-specific domain name or path, and restricted to secure
-resources (sent or downloaded over HTTPS), or restricted
-to the server (disallowing access from client-side scripts).</p></div>
-<div class="paragraph"><p>Cookie names are de facto case sensitive.</p></div>
-<div class="paragraph"><p>Cookies are stored client-side and sent with every subsequent
-request that matches the domain and path for which they were
-stored, until they expire. This can create a non-negligible
-cost.</p></div>
-<div class="paragraph"><p>Cookies should not be considered secure. They are stored on
-the user&#8217;s computer in plain text, and can be read by any
-program. They can also be read by proxies when using clear
-connections. Always validate the value before using it,
-and never store any sensitive information inside it.</p></div>
-<div class="paragraph"><p>Cookies set by the server are only available in requests
-following the client reception of the response containing
-them.</p></div>
-<div class="paragraph"><p>Cookies may be sent repeatedly. This is often useful to
-update the expiration time and avoid losing a cookie.</p></div>
-<div class="sect1">
+<p>Cookies are a mechanism allowing applications to maintain state on top of the stateless HTTP protocol.</p>
+<p>Cookies are a name/value store where the names and values are stored in plain text. They expire either after a delay or when the browser closes. They can be configured on a specific domain name or path, and restricted to secure resources (sent or downloaded over HTTPS), or restricted to the server (disallowing access from client-side scripts).</p>
+<p>Cookie names are de facto case sensitive.</p>
+<p>Cookies are stored client-side and sent with every subsequent request that matches the domain and path for which they were stored, until they expire. This can create a non-negligible cost.</p>
+<p>Cookies should not be considered secure. They are stored on the user&apos;s computer in plain text, and can be read by any program. They can also be read by proxies when using clear connections. Always validate the value before using it, and never store any sensitive information inside it.</p>
+<p>Cookies set by the server are only available in requests following the client reception of the response containing them.</p>
+<p>Cookies may be sent repeatedly. This is often useful to update the expiration time and avoid losing a cookie.</p>
 <h2 id="_setting_cookies">Setting cookies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default cookies are defined for the duration of the session:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<p>By default cookies are defined for the duration of the session:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>They can also be set for a duration in seconds:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt><font color="#009900">SessionID</font> <font color="#990000">=</font> <b><font color="#000000">generate_session_id</font></b>(),
+<font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:set_resp_cookie</font></b>(<font color="#990000">&lt;&lt;</font><font color="#FF0000">"sessionid"</font><font color="#990000">&gt;&gt;</font>, <font color="#009900">SessionID</font>, <font color="#009900">Req0</font>)<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>They can also be set for a duration in seconds:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
-    #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">3600</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To delete cookies, set <code>max_age</code> to 0:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt><font color="#009900">SessionID</font> <font color="#990000">=</font> <b><font color="#000000">generate_session_id</font></b>(),
+<font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:set_resp_cookie</font></b>(<font color="#990000">&lt;&lt;</font><font color="#FF0000">"sessionid"</font><font color="#990000">&gt;&gt;</font>, <font color="#009900">SessionID</font>, <font color="#009900">Req0</font>,
+    #{<font color="#0000FF">max_age</font> <font color="#990000">=&gt;</font> <font color="#993399">3600</font>})<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>To delete cookies, set <code>max_age</code> to 0:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
-    #{<span style="color: #0000FF">max_age</span> <span style="color: #990000">=&gt;</span> <span style="color: #993399">0</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To restrict cookies to a specific domain and path, the options
-of the same name can be used:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt><font color="#009900">SessionID</font> <font color="#990000">=</font> <b><font color="#000000">generate_session_id</font></b>(),
+<font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:set_resp_cookie</font></b>(<font color="#990000">&lt;&lt;</font><font color="#FF0000">"sessionid"</font><font color="#990000">&gt;&gt;</font>, <font color="#009900">SessionID</font>, <font color="#009900">Req0</font>,
+    #{<font color="#0000FF">max_age</font> <font color="#990000">=&gt;</font> <font color="#993399">0</font>})<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>To restrict cookies to a specific domain and path, the options of the same name can be used:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"inaccount"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"1"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #009900">Req0</span>,
-    #{<span style="color: #0000FF">domain</span> <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"my.example.org"</span>, <span style="color: #0000FF">path</span> <span style="color: #990000">=&gt;</span> <span style="color: #FF0000">"/account"</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cookies will be sent with requests to this domain and all
-its subdomains, and to resources on this path or deeper
-in the path hierarchy.</p></div>
-<div class="paragraph"><p>To restrict cookies to secure channels (typically resources
-available over HTTPS):</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt><font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:set_resp_cookie</font></b>(<font color="#990000">&lt;&lt;</font><font color="#FF0000">"inaccount"</font><font color="#990000">&gt;&gt;</font>, <font color="#990000">&lt;&lt;</font><font color="#FF0000">"1"</font><font color="#990000">&gt;&gt;</font>, <font color="#009900">Req0</font>,
+    #{<font color="#0000FF">domain</font> <font color="#990000">=&gt;</font> <font color="#FF0000">"my.example.org"</font>, <font color="#0000FF">path</font> <font color="#990000">=&gt;</font> <font color="#FF0000">"/account"</font>})<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>Cookies will be sent with requests to this domain and all its subdomains, and to resources on this path or deeper in the path hierarchy.</p>
+<p>To restrict cookies to secure channels (typically resources available over HTTPS):</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
-    #{<span style="color: #0000FF">secure</span> <span style="color: #990000">=&gt;</span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>To prevent client-side scripts from accessing a cookie:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt><font color="#009900">SessionID</font> <font color="#990000">=</font> <b><font color="#000000">generate_session_id</font></b>(),
+<font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:set_resp_cookie</font></b>(<font color="#990000">&lt;&lt;</font><font color="#FF0000">"sessionid"</font><font color="#990000">&gt;&gt;</font>, <font color="#009900">SessionID</font>, <font color="#009900">Req0</font>,
+    #{<font color="#0000FF">secure</font> <font color="#990000">=&gt;</font> <font color="#000080">true</font>})<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>To prevent client-side scripts from accessing a cookie:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">SessionID</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">generate_session_id</span></span>(),
-<span style="color: #009900">Req</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:set_resp_cookie</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"sessionid"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #009900">SessionID</span>, <span style="color: #009900">Req0</span>,
-    #{<span style="color: #0000FF">http_only</span> <span style="color: #990000">=&gt;</span> <span style="color: #000080">true</span>})<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Cookies may also be set client-side, for example using
-Javascript.</p></div>
-</div>
-</div>
-<div class="sect1">
+<pre><tt><font color="#009900">SessionID</font> <font color="#990000">=</font> <b><font color="#000000">generate_session_id</font></b>(),
+<font color="#009900">Req</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:set_resp_cookie</font></b>(<font color="#990000">&lt;&lt;</font><font color="#FF0000">"sessionid"</font><font color="#990000">&gt;&gt;</font>, <font color="#009900">SessionID</font>, <font color="#009900">Req0</font>,
+    #{<font color="#0000FF">http_only</font> <font color="#990000">=&gt;</font> <font color="#000080">true</font>})<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>Cookies may also be set client-side, for example using Javascript.</p>
 <h2 id="_reading_cookies">Reading cookies</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The client only ever sends back the cookie name and value.
-All other options that can be set are never sent back.</p></div>
-<div class="paragraph"><p>Cowboy provides two functions for reading cookies. Both
-involve parsing the cookie header(s) and so should not
-be called repeatedly.</p></div>
-<div class="paragraph"><p>You can get all cookies as a key/value list:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<p>The client only ever sends back the cookie name and value. All other options that can be set are never sent back.</p>
+<p>Cowboy provides two functions for reading cookies. Both involve parsing the cookie header(s) and so should not be called repeatedly.</p>
+<p>You can get all cookies as a key/value list:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">Cookies</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:parse_cookies</span></span>(<span style="color: #009900">Req</span>),
-{<span style="color: #990000">_</span>, <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">lists:keyfind</span></span>(<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"lang"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #993399">1</span>, <span style="color: #009900">Cookies</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Or you can perform a match against cookies and retrieve
-only the ones you need, while at the same time doing
-any required post processing using <a href="../constraints">constraints</a>.
-This function returns a map:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt><font color="#009900">Cookies</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:parse_cookies</font></b>(<font color="#009900">Req</font>),
+{<font color="#990000">_</font>, <font color="#009900">Lang</font>} <font color="#990000">=</font> <b><font color="#000000">lists:keyfind</font></b>(<font color="#990000">&lt;&lt;</font><font color="#FF0000">"lang"</font><font color="#990000">&gt;&gt;</font>, <font color="#993399">1</font>, <font color="#009900">Cookies</font>)<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>Or you can perform a match against cookies and retrieve only the ones you need, while at the same time doing any required post processing using <a href="../constraints">constraints</a>. This function returns a map:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt>#{<span style="color: #FF6600">id</span> <span style="color: #990000">:=</span> <span style="color: #009900">ID</span>, <span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([<span style="color: #FF6600">id</span>, <span style="color: #FF6600">lang</span>], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>You can use constraints to validate the values while matching
-them. The following snippet will crash if the <code>id</code> cookie is
-not an integer number or if the <code>lang</code> cookie is empty. Additionally
-the <code>id</code> cookie value will be converted to an integer term:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt>#{<font color="#FF6600">id</font> <font color="#990000">:=</font> <font color="#009900">ID</font>, <font color="#FF6600">lang</font> <font color="#990000">:=</font> <font color="#009900">Lang</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy_req:match_cookies</font></b>([<font color="#FF6600">id</font>, <font color="#FF6600">lang</font>], <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>You can use constraints to validate the values while matching them. The following snippet will crash if the <code>id</code> cookie is not an integer number or if the <code>lang</code> cookie is empty. Additionally the <code>id</code> cookie value will be converted to an integer term:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt><span style="color: #009900">CookiesMap</span> <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">id</span>, <span style="color: #FF6600">int</span>}, {<span style="color: #FF6600">lang</span>, <span style="color: #FF6600">nonempty</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>Note that if two cookies share the same name, then the map value
-will be a list of the two cookie values.</p></div>
-<div class="paragraph"><p>A default value can be provided. The default will be used
-if the <code>lang</code> cookie is not found. It will not be used if
-the cookie is found but has an empty value:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt><font color="#009900">CookiesMap</font> <font color="#990000">=</font> <b><font color="#000000">cowboy_req:match_cookies</font></b>([{<font color="#FF6600">id</font>, <font color="#FF6600">int</font>}, {<font color="#FF6600">lang</font>, <font color="#FF6600">nonempty</font>}], <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>Note that if two cookies share the same name, then the map value will be a list of the two cookie values.</p>
+<p>A default value can be provided. The default will be used if the <code>lang</code> cookie is not found. It will not be used if the cookie is found but has an empty value:</p>
+<div class="listingblock"><div class="content"><!-- Generator: GNU source-highlight 3.1.8
 by Lorenzo Bettini
 http://www.lorenzobettini.it
 http://www.gnu.org/software/src-highlite -->
-<pre><tt>#{<span style="color: #FF6600">lang</span> <span style="color: #990000">:=</span> <span style="color: #009900">Lang</span>} <span style="color: #990000">=</span> <span style="font-weight: bold"><span style="color: #000000">cowboy_req:match_cookies</span></span>([{<span style="color: #FF6600">lang</span>, [], <span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"en-US"</span><span style="color: #990000">&gt;&gt;</span>}], <span style="color: #009900">Req</span>)<span style="color: #990000">.</span></tt></pre></div></div>
-<div class="paragraph"><p>If no default is provided and the value is missing, an
-exception is thrown.</p></div>
-</div>
-</div>
+<pre><tt>#{<font color="#FF6600">lang</font> <font color="#990000">:=</font> <font color="#009900">Lang</font>} <font color="#990000">=</font> <b><font color="#000000">cowboy_req:match_cookies</font></b>([{<font color="#FF6600">lang</font>, [], <font color="#990000">&lt;&lt;</font><font color="#FF0000">"en-US"</font><font color="#990000">&gt;&gt;</font>}], <font color="#009900">Req</font>)<font color="#990000">.</font></tt></pre>
+</div></div>
+<p>If no default is provided and the value is missing, an exception is thrown.</p>
+