Rebuild using Asciideck

1 files changed, 61 insertions, 133 deletions

diff --git a/docs/en/cowboy/2.3/guide/static_files/index.html b/docs/en/cowboy/2.3/guide/static_files/index.html
index 5b5bbd0b..f3fe3254 100644
--- a/docs/en/cowboy/2.3/guide/static_files/index.html
+++ b/docs/en/cowboy/2.3/guide/static_files/index.html
@@ -62,173 +62,101 @@
 
 <h1 class="lined-header"><span>Static files</span></h1>
 
-<div class="paragraph"><p>Cowboy comes with a ready to use handler for serving static
-files. It is provided as a convenience for serving files
-during development.</p></div>
-<div class="paragraph"><p>For systems in production, consider using one of the many
-Content Distribution Network (CDN) available on the market,
-as they are the best solution for serving files.</p></div>
-<div class="paragraph"><p>The static handler can serve either one file or all files
-from a given directory. The etag generation and mime types
-can be configured.</p></div>
-<div class="sect1">
+<p>Cowboy comes with a ready to use handler for serving static files. It is provided as a convenience for serving files during development.</p>
+<p>For systems in production, consider using one of the many Content Distribution Network (CDN) available on the market, as they are the best solution for serving files.</p>
+<p>The static handler can serve either one file or all files from a given directory. The etag generation and mime types can be configured.</p>
 <h2 id="_serve_one_file">Serve one file</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can use the static handler to serve one specific file
-from an application&#8217;s private directory. This is particularly
-useful to serve an <em>index.html</em> file when the client requests
-the <code>/</code> path, for example. The path configured is relative
-to the given application&#8217;s private directory.</p></div>
-<div class="paragraph"><p>The following rule will serve the file <em>static/index.html</em>
-from the application <code>my_app</code>'s priv directory whenever the
-path <code>/</code> is accessed:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<p>You can use the static handler to serve one specific file from an application&apos;s private directory. This is particularly useful to serve an <em>index.html</em> file when the client requests the <code>/</code> path, for example. The path configured is relative to the given application&apos;s private directory.</p>
+<p>The following rule will serve the file <em>static/index.html</em> from the application <code>my_app</code>&apos;s priv directory whenever the path <code>/</code> is accessed:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>}}</tt></pre></div></div>
-<div class="paragraph"><p>You can also specify the absolute path to a file, or the
-path to the file relative to the current directory:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt>{<font color="#FF0000">"/"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_file</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/index.html"</font>}}</tt></pre>
+</div></div>
+<p>You can also specify the absolute path to a file, or the path to the file relative to the current directory:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">file</span>, <span style="color: #FF0000">"/var/www/index.html"</span>}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
+<pre><tt>{<font color="#FF0000">"/"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">file</font>, <font color="#FF0000">"/var/www/index.html"</font>}}</tt></pre>
+</div></div>
 <h2 id="_serve_all_files_from_a_directory">Serve all files from a directory</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>You can also use the static handler to serve all files that
-can be found in the configured directory. The handler will
-use the <code>path_info</code> information to resolve the file location,
-which means that your route must end with a <code>[...]</code> pattern
-for it to work. All files are served, including the ones that
-may be found in subfolders.</p></div>
-<div class="paragraph"><p>You can specify the directory relative to an application&#8217;s
-private directory.</p></div>
-<div class="paragraph"><p>The following rule will serve any file found in the application
-<code>my_app</code>'s priv directory inside the <code>static/assets</code> folder
-whenever the requested path begins with <code>/assets/</code>:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<p>You can also use the static handler to serve all files that can be found in the configured directory. The handler will use the <code>path_info</code> information to resolve the file location, which means that your route must end with a <code>[...]</code> pattern for it to work. All files are served, including the ones that may be found in subfolders.</p>
+<p>You can specify the directory relative to an application&apos;s private directory.</p>
+<p>The following rule will serve any file found in the application <code>my_app</code>&apos;s priv directory inside the <code>static/assets</code> folder whenever the requested path begins with <code>/assets/</code>:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>}}</tt></pre></div></div>
-<div class="paragraph"><p>You can also specify the absolute path to the directory or
-set it relative to the current directory:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_dir</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/assets"</font>}}</tt></pre>
+</div></div>
+<p>You can also specify the absolute path to the directory or set it relative to the current directory:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">dir</span>, <span style="color: #FF0000">"/var/www/assets"</span>}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
+<pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">dir</font>, <font color="#FF0000">"/var/www/assets"</font>}}</tt></pre>
+</div></div>
 <h2 id="_customize_the_mimetype_detection">Customize the mimetype detection</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, Cowboy will attempt to recognize the mimetype
-of your static files by looking at the extension.</p></div>
-<div class="paragraph"><p>You can override the function that figures out the mimetype
-of the static files. It can be useful when Cowboy is missing
-a mimetype you need to handle, or when you want to reduce
-the list to make lookups faster. You can also give a
-hard-coded mimetype that will be used unconditionally.</p></div>
-<div class="paragraph"><p>Cowboy comes with two functions built-in. The default
-function only handles common file types used when building
-Web applications. The other function is an extensive list
-of hundreds of mimetypes that should cover almost any need
-you may have. You can of course create your own function.</p></div>
-<div class="paragraph"><p>To use the default function, you should not have to configure
-anything, as it is the default. If you insist, though, the
-following will do the job:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<p>By default, Cowboy will attempt to recognize the mimetype of your static files by looking at the extension.</p>
+<p>You can override the function that figures out the mimetype of the static files. It can be useful when Cowboy is missing a mimetype you need to handle, or when you want to reduce the list to make lookups faster. You can also give a hard-coded mimetype that will be used unconditionally.</p>
+<p>Cowboy comes with two functions built-in. The default function only handles common file types used when building Web applications. The other function is an extensive list of hundreds of mimetypes that should cover almost any need you may have. You can of course create your own function.</p>
+<p>To use the default function, you should not have to configure anything, as it is the default. If you insist, though, the following will do the job:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
-    [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">web</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>As you can see, there is an optional field that may contain
-a list of less used options, like mimetypes or etag. All option
-types have this optional field.</p></div>
-<div class="paragraph"><p>To use the function that will detect almost any mimetype,
-the following configuration will do:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_dir</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/assets"</font>,
+    [{<font color="#FF6600">mimetypes</font>, <font color="#FF6600">cow_mimetypes</font>, <font color="#FF6600">web</font>}]}}</tt></pre>
+</div></div>
+<p>As you can see, there is an optional field that may contain a list of less used options, like mimetypes or etag. All option types have this optional field.</p>
+<p>To use the function that will detect almost any mimetype, the following configuration will do:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
-    [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #FF6600">cow_mimetypes</span>, <span style="color: #FF6600">all</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>You probably noticed the pattern by now. The configuration
-expects a module and a function name, so you can use any
-of your own functions instead:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_dir</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/assets"</font>,
+    [{<font color="#FF6600">mimetypes</font>, <font color="#FF6600">cow_mimetypes</font>, <font color="#FF6600">all</font>}]}}</tt></pre>
+</div></div>
+<p>You probably noticed the pattern by now. The configuration expects a module and a function name, so you can use any of your own functions instead:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
-    [{<span style="color: #FF6600">mimetypes</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>The function that performs the mimetype detection receives
-a single argument that is the path to the file on disk. It
-is recommended to return the mimetype in tuple form, although
-a binary string is also allowed (but will require extra
-processing). If the function can&#8217;t figure out the mimetype,
-then it should return <code>{&lt;&lt;"application"&gt;&gt;, &lt;&lt;"octet-stream"&gt;&gt;, []}</code>.</p></div>
-<div class="paragraph"><p>When the static handler fails to find the extension,
-it will send the file as <code>application/octet-stream</code>.
-A browser receiving such file will attempt to download it
-directly to disk.</p></div>
-<div class="paragraph"><p>Finally, the mimetype can be hard-coded for all files.
-This is especially useful in combination with the <code>file</code>
-and <code>priv_file</code> options as it avoids needless computation:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_dir</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/assets"</font>,
+    [{<font color="#FF6600">mimetypes</font>, <font color="#009900">Module</font>, <font color="#009900">Function</font>}]}}</tt></pre>
+</div></div>
+<p>The function that performs the mimetype detection receives a single argument that is the path to the file on disk. It is recommended to return the mimetype in tuple form, although a binary string is also allowed (but will require extra processing). If the function can&apos;t figure out the mimetype, then it should return <code>{&lt;&lt;&quot;application&quot;&gt;&gt;, &lt;&lt;&quot;octet-stream&quot;&gt;&gt;, []}</code>.</p>
+<p>When the static handler fails to find the extension, it will send the file as <code>application/octet-stream</code>. A browser receiving such file will attempt to download it directly to disk.</p>
+<p>Finally, the mimetype can be hard-coded for all files. This is especially useful in combination with the <code>file</code> and <code>priv_file</code> options as it avoids needless computation:</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: #FF0000">"/"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_file</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/index.html"</span>,
-    [{<span style="color: #FF6600">mimetypes</span>, {<span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"text"</span><span style="color: #990000">&gt;&gt;</span>, <span style="color: #990000">&lt;&lt;</span><span style="color: #FF0000">"html"</span><span style="color: #990000">&gt;&gt;</span>, []}}]}}</tt></pre></div></div>
-</div>
-</div>
-<div class="sect1">
+<pre><tt>{<font color="#FF0000">"/"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_file</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/index.html"</font>,
+    [{<font color="#FF6600">mimetypes</font>, {<font color="#990000">&lt;&lt;</font><font color="#FF0000">"text"</font><font color="#990000">&gt;&gt;</font>, <font color="#990000">&lt;&lt;</font><font color="#FF0000">"html"</font><font color="#990000">&gt;&gt;</font>, []}}]}}</tt></pre>
+</div></div>
 <h2 id="_generate_an_etag">Generate an etag</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>By default, the static handler will generate an etag header
-value based on the size and modified time. This solution
-can not be applied to all systems though. It would perform
-rather poorly over a cluster of nodes, for example, as the
-file metadata will vary from server to server, giving a
-different etag on each server.</p></div>
-<div class="paragraph"><p>You can however change the way the etag is calculated:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<p>By default, the static handler will generate an etag header value based on the size and modified time. This solution can not be applied to all systems though. It would perform rather poorly over a cluster of nodes, for example, as the file metadata will vary from server to server, giving a different etag on each server.</p>
+<p>You can however change the way the etag is calculated:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
-    [{<span style="color: #FF6600">etag</span>, <span style="color: #009900">Module</span>, <span style="color: #009900">Function</span>}]}}</tt></pre></div></div>
-<div class="paragraph"><p>This function will receive three arguments: the path to the
-file on disk, the size of the file and the last modification
-time. In a distributed setup, you would typically use the
-file path to retrieve an etag value that is identical across
-all your servers.</p></div>
-<div class="paragraph"><p>You can also completely disable etag handling:</p></div>
-<div class="listingblock">
-<div class="content"><!-- Generator: GNU source-highlight
+<pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_dir</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/assets"</font>,
+    [{<font color="#FF6600">etag</font>, <font color="#009900">Module</font>, <font color="#009900">Function</font>}]}}</tt></pre>
+</div></div>
+<p>This function will receive three arguments: the path to the file on disk, the size of the file and the last modification time. In a distributed setup, you would typically use the file path to retrieve an etag value that is identical across all your servers.</p>
+<p>You can also completely disable etag handling:</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: #FF0000">"/assets/[...]"</span>, <span style="color: #FF6600">cowboy_static</span>, {<span style="color: #FF6600">priv_dir</span>, <span style="color: #FF6600">my_app</span>, <span style="color: #FF0000">"static/assets"</span>,
-    [{<span style="color: #FF6600">etag</span>, <span style="color: #000080">false</span>}]}}</tt></pre></div></div>
-</div>
-</div>
+<pre><tt>{<font color="#FF0000">"/assets/[...]"</font>, <font color="#FF6600">cowboy_static</font>, {<font color="#FF6600">priv_dir</font>, <font color="#FF6600">my_app</font>, <font color="#FF0000">"static/assets"</font>,
+    [{<font color="#FF6600">etag</font>, <font color="#000080">false</font>}]}}</tt></pre>
+</div></div>
+