Convert documentation to HTML, fix styling.

3 files changed, 293 insertions, 263 deletions

diff --git a/libpathod/static/pathod.css b/libpathod/static/pathod.css
new file mode 100644
index 00000000..3e24dd7d
--- /dev/null
+++ b/libpathod/static/pathod.css
@@ -0,0 +1,19 @@
+
+
+section {
+    margin-top: 50px;
+
+}
+
+.example {
+    margin-top: 10px;
+    margin-bottom: 10px;
+
+}
+
+.terminal {
+    margin-top: 10px;
+    margin-bottom: 10px;
+    background: #000;
+    color: #fff;
+}
diff --git a/libpathod/templates/docs_pathod.html b/libpathod/templates/docs_pathod.html
index f3dabd5e..1527f851 100644
--- a/libpathod/templates/docs_pathod.html
+++ b/libpathod/templates/docs_pathod.html
@@ -1,5 +1,6 @@
 {% extends "frame.html" %}
 {% block body %}  
+
 <div class="page-header">
    <h1>
         pathod
@@ -7,340 +8,349 @@
     </h1>
 </div>
 
-At pathod's heart is a small, terse language for crafting HTTP responses,
+<p>At pathod's heart is a small, terse language for crafting HTTP responses,
 designed to be easy to specify in a request URL.  The simplest way to use
 pathod is to fire up the daemon, and specify the response behaviour you
-want using this language in the request URL.  Here's a minimal example:
+want using this language in the request URL.  Here's a minimal example:</p>
 
-    http://localhost:9999/p/200
+<pre class="example">http://localhost:9999/p/200</pre>
 
-Everything after the "/p/" path component is a response specifier - in this
+<p>Everything after the "/p/" path component is a response specifier - in this
 case just a vanilla 200 OK response. See the docs below to get (much) fancier.
 You can also add anchors to the pathod server that serve a fixed response
-whenever a matching URL is requested:
+whenever a matching URL is requested:</p>
 
-    pathod -a "/foo=200"
+<pre class="terminal">pathod -a "/foo=200"</pre>
 
-Here, "/foo" a regex specifying the anchor path, and the part after the "=" is
-a response specifier.
+<p>Here, "/foo" a regex specifying the anchor path, and the part after the "=" is
+a response specifier.</p>
 
-pathod also has a nifty built-in web interface, which lets you play with
+<p>pathod also has a nifty built-in web interface, which lets you play with
 the language by previewing responses, exposes activity logs, online help and
-various other goodies. Try it by visiting the server root:
-
-    http://localhost:9999
-
+various other goodies. Try it by visiting the server root:</p>
 
+<pre class="example">http://localhost:9999</pre>
 
-<div class="page-header">
-   <h1>Specifying Responses</h1>
-</div>
-
-The general form of a response is as follows:
-    
-    code[MESSAGE]:[colon-separated list of features]
 
-Here's the simplest possible response specification, returning just an HTTP 200
-OK message with no headers and no content:
-    
-    200
+<section id="specifying_responses">
 
-We can embellish this a bit by specifying an optional custom HTTP response
-message (if we don't, pathod automatically creates an appropriate one). By
-default for a 200 response code the message is "OK", but we can change it like
-this:
+    <div class="page-header">
+       <h1>Specifying Responses</h1>
+    </div>
 
-    200"YAY"
+    <p>The general form of a response is as follows:
+        
+    <pre class="example">code[MESSAGE]:[colon-separated list of features]</pre></p>
 
-The quoted string here is an example of a <a href=#valuespec>Value
-Specifier</a>, a syntax that is used throughout the pathod response
-specification language. In this case, the quotes mean we're specifying a
-literal string, but there are many other fun things we can do. For example, we
-can tell pathod to generate 100k of random ASCII letters instead:
+    <p>Here's the simplest possible response specification, returning just an HTTP 200
+    OK message with no headers and no content:
+        
+    <pre class="example">200</pre></p>
 
-    200@100k,ascii_letters
+    <p>We can embellish this a bit by specifying an optional custom HTTP response
+    message (if we don't, pathod automatically creates an appropriate one). By
+    default for a 200 response code the message is "OK", but we can change it like
+    this:</p>
 
-Full documentation on the value specification syntax can be found in the next
-section. 
-   
-Following the response code specifier is a colon-separated list of features.
-For instance, this specifies a response with a body consisting of 1 megabyte of
-random data:
+    <pre class="example">200"YAY"</pre>
 
-    200:b@1m
+    <p>The quoted string here is an example of a <a href=#valuespec>Value
+    Specifier</a>, a syntax that is used throughout the pathod response
+    specification language. In this case, the quotes mean we're specifying a
+    literal string, but there are many other fun things we can do. For example, we
+    can tell pathod to generate 100k of random ASCII letters instead:</p>
 
-And this is the same response with an ETag header added:
+    <pre class="example">200@100k,ascii_letters</pre>
 
-    200:b@1m:h"Etag"="foo"
+    <p>Full documentation on the value specification syntax can be found in the next
+    section. 
+       
+    Following the response code specifier is a colon-separated list of features.
+    For instance, this specifies a response with a body consisting of 1 megabyte of
+    random data:</p>
 
-Both the header name and the header value are full value specifiers. Here's the
-same response again, but with a 1k randomly generated header name:
+    <pre class="example">200:b@1m</pre>
 
-    200:b@1m:h@1k,ascii_letters="foo"
+    <p>And this is the same response with an ETag header added:</p>
 
-A few specific headers have shortcuts, because they're used so often. The
-shortcut for the content-type header is "c":
+    <pre class="example">200:b@1m:h"Etag"="foo"</pre>
 
-    200:b@1m:c"text/json"
+    <p>Both the header name and the header value are full value specifiers. Here's the
+    same response again, but with a 1k randomly generated header name:</p>
 
-That's it for the basic response definition. Now we can start mucking with the
-responses to break clients. One common hard-to-test circumstance is hangs or
-slow responses. pathod has a pause operator that you can use to define
-precisely when and how long the server should hang. Here, for instance, we hang
-for 120 seconds after sending 50 bytes (counted from the first byte of the HTTP
-response):
+    <pre class="example">200:b@1m:h@1k,ascii_letters="foo"</pre>
 
-    200:b@1m:p120,50
+    <p>A few specific headers have shortcuts, because they're used so often. The
+    shortcut for the content-type header is "c":</p>
 
-If that's not long enough, we can tell pathod to hang forever:
+    <pre class="example">200:b@1m:c"text/json"</pre>
 
-    200:b@1m:p120,f
+    <p>That's it for the basic response definition. Now we can start mucking with the
+    responses to break clients. One common hard-to-test circumstance is hangs or
+    slow responses. pathod has a pause operator that you can use to define
+    precisely when and how long the server should hang. Here, for instance, we hang
+    for 120 seconds after sending 50 bytes (counted from the first byte of the HTTP
+    response):</p>
 
-Or to send all data, and then hang without disconnecting:
+    <pre class="example">200:b@1m:p120,50</pre>
 
-    200:b@1m:p120,a
+    <p>If that's not long enough, we can tell pathod to hang forever:</p>
 
-We can also ask pathod to hang randomly:
+    <pre class="example">200:b@1m:p120,f</pre>
 
-    200:b@1m:pr,a
+    <p>Or to send all data, and then hang without disconnecting:</p>
 
-There is a similar mechanism for dropping connections mid-response. So, we can
-tell pathod to disconnect after sending 50 bytes:
+    <pre class="example">200:b@1m:p120,a</pre>
 
-    200:b@1m:d50
+    <p>We can also ask pathod to hang randomly:</p>
 
-Or randomly:
+    <pre class="example">200:b@1m:pr,a</pre>
 
-    200:b@1m:dr
+    <p>There is a similar mechanism for dropping connections mid-response. So, we can
+    tell pathod to disconnect after sending 50 bytes:</p>
 
-All of these features can be combined. Here's a response that pauses twice,
-once at 10 bytes and once at 20, then disconnects at 5000:
+    <pre class="example">200:b@1m:d50</pre>
 
-    200:b@1m:p10,10:p20,10:d5000
+    <p>Or randomly:</p>
 
+    <pre class="example">200:b@1m:dr</pre>
 
-## Response Features
+    <p>All of these features can be combined. Here's a response that pauses twice,
+    once at 10 bytes and once at 20, then disconnects at 5000:</p>
 
-<table class="table table-bordered table-condensed">
-    <tbody >
-        <tr>
-            <td>
-                hKEY=VALUE
-            </td>
-            <td>
-                Set a header. Both KEY and VALUE are full <a href=#valuespec>Value Specifiers</a>. 
-            </td>
-        </tr>
+    <pre class="example">200:b@1m:p10,10:p20,10:d5000</pre>
 
-        <tr>
-            <td> 
-                bVALUE
-            </td>
-            <td>
-                Set the body. VALUE is a <a href=#valuespec>Value
-                Specifier</a>. When the body is set, pathod will
-                automatically set the appropriate Content-Length header.
-            </td>
-        </tr>
 
-        <tr>
-            <td>
-                cVALUE
-            </td>
-            <td>
-                A shortcut for setting the Content-Type header. Equivalent to:
+    <h2>Response Features</h2>
 
-                <pre>h"Content-Type"=VALUE</pre>
+    <table class="table table-bordered">
+        <tbody >
+            <tr>
+                <td>
+                    hKEY=VALUE
+                </td>
+                <td>
+                    Set a header. Both KEY and VALUE are full <a href=#valuespec>Value Specifiers</a>. 
+                </td>
+            </tr>
 
-            </td>
-        </tr>
+            <tr>
+                <td> 
+                    bVALUE
+                </td>
+                <td>
+                    Set the body. VALUE is a <a href=#valuespec>Value
+                    Specifier</a>. When the body is set, pathod will
+                    automatically set the appropriate Content-Length header.
+                </td>
+            </tr>
 
-        <tr>
-            <td>
-                lVALUE
-            </td>
-            <td>
-                A shortcut for setting the Location header. Equivalent to:
+            <tr>
+                <td>
+                    cVALUE
+                </td>
+                <td>
+                    A shortcut for setting the Content-Type header. Equivalent to:
 
                     <pre>h"Content-Type"=VALUE</pre>
 
-            </td>
-        </tr>
-
-
-        <tr>
-            <td>
-                dOFFSET
-            </td>
-            <td>
-                Disconnect after OFFSET bytes. The offset can also be "r", in which case pathod
-                will disconnect at a random point in the response.
-            </td>
-        </tr>
-
-        <tr>
-            <td>
-                pSECONDS,OFFSET
-            </td>
-            <td>
-                Pause for SECONDS seconds after OFFSET bytes. SECONDS can also be "f" to pause
-                forever. OFFSET can also be "r" to generate a random offset, or "a" for an
-                offset just after all data has been sent.
-            </td>
-        </tr>
-    </tbody>
-</table>
-
-<a id="valuespec"></a>
-## VALUE Specifiers
-
-There are three different flavours of value specification. 
-
-### Literal
+                </td>
+            </tr>
 
-Literal values are specified as a quoted strings: 
+            <tr>
+                <td>
+                    lVALUE
+                </td>
+                <td>
+                    A shortcut for setting the Location header. Equivalent to:
 
-    "foo"
+                        <pre>h"Location"=VALUE</pre>
 
-Either single or double quotes are accepted, and quotes can be escaped with
-backslashes within the string:
+                </td>
+            </tr>
 
-    'fo\'o'
 
+            <tr>
+                <td>
+                    dOFFSET
+                </td>
+                <td>
+                    Disconnect after OFFSET bytes. The offset can also be "r", in which case pathod
+                    will disconnect at a random point in the response.
+                </td>
+            </tr>
 
-### Files
+            <tr>
+                <td>
+                    pSECONDS,OFFSET
+                </td>
+                <td>
+                    Pause for SECONDS seconds after OFFSET bytes. SECONDS can also be "f" to pause
+                    forever. OFFSET can also be "r" to generate a random offset, or "a" for an
+                    offset just after all data has been sent.
+                </td>
+            </tr>
+        </tbody>
+    </table>
 
-You can load a value from a specified file path. To do so, you have to specify
-a _staticdir_ option to pathod on the command-line, like so: 
+    <a id="valuespec"></a>
+    <h2>VALUE Specifiers</h2>
 
-    pathod -d ~/myassets
+    <h3>Literals</h3>
 
-All paths are relative paths under this directory. File loads are indicated by
-starting the value specifier with the left angle bracket:
-    
-    <my/path
+    <p>Literal values are specified as a quoted strings: </p>
 
-The path value can also be a quoted string, with the same syntax as literals:
+    <pre class="example">"foo"</pre>
 
-    <"my/path"
+    <p>Either single or double quotes are accepted, and quotes can be escaped with
+    backslashes within the string:</p>
 
+    <pre class="example">'fo\'o'</pre>
 
-### Generated values
 
-An @-symbol lead-in specifies that generated data should be used. There are two
-components to a generator specification - a size, and a data type. By default
-pathod assumes a data type of "bytes". 
+    <h3>Files</h3>
 
-Here's a value specifier for generating 100 bytes:
-    
-    @100
+    <p>You can load a value from a specified file path. To do so, you have to specify
+    a _staticdir_ option to pathod on the command-line, like so: </p>
 
-You can use standard suffixes to indicate larger values. Here, for instance, is
-a specifier for generating 100 megabytes:
+    <pre class="example">pathod -d ~/myassets</pre>
 
-    @100m
+    <p>All paths are relative paths under this directory. File loads are indicated by
+    starting the value specifier with the left angle bracket:
+        
+    <pre class="example">&lt;my/path</pre></p>
+
+    <p>The path value can also be a quoted string, with the same syntax as literals:</p>
+
+    <pre class="example">&lt;"my/path"</pre>
+
+
+    <h3>Generated values</h3>
+
+    <p>An @-symbol lead-in specifies that generated data should be used. There are two
+    components to a generator specification - a size, and a data type. By default
+    pathod assumes a data type of "bytes". </p>
+
+    <p>Here's a value specifier for generating 100 bytes:
+        
+    <pre class="example">@100</pre></p>
+
+    <p>You can use standard suffixes to indicate larger values. Here, for instance, is
+    a specifier for generating 100 megabytes:</p>
+
+    <pre class="example">@100m</pre>
+
+    <p>Data is generated and served efficiently - if you really want to send a
+    terabyte of data to a client, pathod can do it. The supported suffixes are:</p>
+
+
+    <table class="table table-bordered">
+        <tbody >
+            <tr>
+                <td>b</td> <td>1024**0 (bytes)</td>
+            </tr>
+            <tr>
+                <td>k</td> <td>1024**1 (kilobytes)</td>
+            </tr>
+            <tr>
+                <td>m</td> <td>1024**2 (megabytes)</td>
+            </tr>
+            <tr>
+                <td>g</td> <td>1024**3 (gigabytes)</td>
+            </tr>
+            <tr>
+                <td>t</td> <td>1024**4 (terabytes)</td>
+            </tr>
+        </tbody>
+    </table>
+
+    <p>Data types are separated from the size specification by a comma. This
+    specification generates 100mb of ASCII:</p>
+
+    <pre class="example">@100m,ascii</pre>
+
+    <p>Supported data types are:</p>
+
+
+    <ul>
+        <li>ascii_letters</li>
+        <li>ascii_lowercase</li>
+        <li>ascii_uppercase</li>
+        <li>digits</li>
+        <li>hexdigits</li>
+        <li>letters</li>
+        <li>lowercase</li>
+        <li>octdigits</li>
+        <li>printable</li>
+        <li>punctuation</li>
+        <li>uppercase</li>
+        <li>whitespace</li>
+        <li>ascii</li>
+        <li>bytes</li>
+    </ul>
 
-Data is generated and served efficiently - if you really want to send a
-terabyte of data to a client, pathod can do it. The supported suffixes are:
+</section>
 
 
-<table class="table table-bordered table-condensed">
-    <tbody >
-        <tr>
-            <td>b</td> <td>1024**0 (bytes)</td>
-        </tr>
-        <tr>
-            <td>k</td> <td>1024**1 (kilobytes)</td>
-        </tr>
-        <tr>
-            <td>m</td> <td>1024**2 (megabytes)</td>
-        </tr>
-        <tr>
-            <td>g</td> <td>1024**3 (gigabytes)</td>
-        </tr>
-        <tr>
-            <td>t</td> <td>1024**4 (terabytes)</td>
-        </tr>
-    </tbody>
-</table>
-
-Data types are separated from the size specification by a comma. This
-specification generates 100mb of ASCII:
-
-    @100m,ascii
-
-Supported data types are:
-
-    
-- ascii_letters
-- ascii_lowercase
-- ascii_uppercase
-- digits
-- hexdigits
-- letters
-- lowercase
-- octdigits
-- printable
-- punctuation
-- uppercase
-- whitespace
-- ascii
-- bytes
-
-
-<div class="page-header">
-   <h1>API</h1>
-</div>
-
-pathod exposes a simple API, intended to make it possible to drive and
-inspect the daemon remotely for use in unit testing and the like. 
-
-
-<table class="table table-bordered table-condensed">
-    <tbody >
-        <tr>
-            <td>
-                /api/clear_log
-            </td>
-            <td>
-                A POST to this URL clears the log buffer.
-            </td>
-        </tr>
-        <tr>
-            <td>
-                /api/info
-            </td>
-            <td>
-                Basic version and configuration info.
-            </td>
-        </tr>
-        <tr>
-            <td>
-                /api/log
-            </td>
-            <td>
-                Returns the current log buffer. At the moment the buffer size is 500 entries -
-                when the log grows larger than this, older entries are discarded. The returned
-                data is a JSON dictionary, with the form:
-
-                <pre>{ 'log': [ ENTRIES ] } </pre>
-
-                You can preview the JSON data returned for a log entry through the built-in web
-                interface.
-            </td>
-        </tr>
-    </tbody>
-</table>
-
-<div class="page-header">
-   <h1>Error Responses</h1>
-</div>
+<section id="api">
+    <div class="page-header">
+       <h1>API</h1>
+    </div>
 
-To let users distinguish crafted responses from internal pathod responses,
-pathod uses the non-standard 800 response code to indicate errors. For example,
-a request to:
+    <p>pathod exposes a simple API, intended to make it possible to drive and
+    inspect the daemon remotely for use in unit testing and the like. </p>
 
-    http://localhost:9999/p/foo
 
-... will return an 800 response, because "foo" is not a valid page specifier.
+    <table class="table table-bordered">
+        <tbody >
+            <tr>
+                <td>
+                    /api/clear_log
+                </td>
+                <td>
+                    A POST to this URL clears the log buffer.
+                </td>
+            </tr>
+            <tr>
+                <td>
+                    /api/info
+                </td>
+                <td>
+                    Basic version and configuration info.
+                </td>
+            </tr>
+            <tr>
+                <td>
+                    /api/log
+                </td>
+                <td>
+                    Returns the current log buffer. At the moment the buffer size is 500 entries -
+                    when the log grows larger than this, older entries are discarded. The returned
+                    data is a JSON dictionary, with the form:
+
+                    <pre>{ 'log': [ ENTRIES ] } </pre>
+
+                    You can preview the JSON data returned for a log entry through the built-in web
+                    interface.
+                </td>
+            </tr>
+        </tbody>
+    </table>
+</section>
+
+<section>
+    <div class="page-header">
+       <h1>Error Responses</h1>
+    </div>
+
+    <p>To let users distinguish crafted responses from internal pathod responses,
+    pathod uses the non-standard 800 response code to indicate errors. For example,
+    a request to:</p>
+
+    <pre class="example">http://localhost:9999/p/foo</pre>
+
+    <p>... will return an 800 response, because "foo" is not a valid page specifier.</p>
+
+</section>
+
 {% endblock %}  
diff --git a/libpathod/templates/frame.html b/libpathod/templates/frame.html
index a83f8f38..daf3e2ae 100644
--- a/libpathod/templates/frame.html
+++ b/libpathod/templates/frame.html
@@ -4,6 +4,7 @@
     <meta charset="utf-8">
     <title>pathod</title>
     <link href="/static/bootstrap.min.css" rel="stylesheet">
+    <link href="/static/pathod.css" rel="stylesheet">
     <link href="/static/syntax.css" rel="stylesheet">
     <script src="/static/jquery-1.7.2.min.js"></script>
     <script src="/static/bootstrap.min.js"></script>