Document embedded response specification.

libpathod/templates/about.html

@@ -19,7 +19,6 @@
             <ul>
                 <li>email: <a href="mailto:aldo@corte.si">aldo@corte.si</a></li>
                 <li>twitter: <a href="http://twitter.com/cortesi">@cortesi</a></li>
-                <li>app.net: <a href="https://alpha.app.net/cortesi">@cortesi</a></li>
                 <li>github: <a href="https://github.com/cortesi">github.com/cortesi</a></li>
             </ul>
         </div>

libpathod/templates/docs_lang.html

@@ -156,6 +156,14 @@
                     </td>
                 </tr>
 
+                <tr>
+                    <td> s<a href="#valuespec">VALUE</a> </td>
+                    <td>
+                        An embedded Response specification, appended to the path
+                        of the request.
+                    </td>
+                </tr>
+
                 <tr>
                     <td> u<a href="#valuespec">VALUE</a> <br> uSHORTCUT </td>
 

libpathod/templates/docs_pathoc.html

@@ -149,4 +149,43 @@ the command-line help:</p>
 </section>
 
 
+<section>
+    <div class="page-header">
+       <h1>Embedded response specification</h1>
+    </div>
+
+    <p>One interesting feature of the Request sppecification language is that
+    you can embed a response specifcation in it, which is then added to the
+    request path. Here's an example:</p>
+
+    <pre class="terminal">&gt; pathoc localhost:9999 "get:/p/:s'401:ir,@1'" </pre>
+
+    <p> This crafts a request that connects to the pathod server, and which then
+    crafts a response that generates a 401, with one random byte embedded at a
+    random point. The response specification is parsed and expanded by pathoc,
+    so you see syntax errors immediately. This really becomes handy when
+    combined with the <b>-e</b> flag to show the expanded request:
+
+    <pre class="terminal">&gt; > pathoc -e localhost:9999 "get:/p/:s'401:ir,@1'"
+>> Spec: get:/p/:s'401:i15,\'o\':h\'Content-Length\'=\'0\'':h'Content-Length'='0'
+<< 401 Unoauthorized: 0 bytes </pre>
+
+    <p> Note that the embedded response has been resolved <i>before</i> being
+    sent to the server, so that "ir,@1" (embed a random byte at a random
+    location) has become "i15,\'o\'" (embed the character "o" at offset 15). You
+    now have a pathoc request specification that is precisely reproducable, even
+    with random components. This feature comes in terribly handy when testing a
+    proxy, since you can now drive the server repsonse completely from the
+    client, and have a complete log of reproducible requests to analyse
+    afterwards.</p>
+
+</section>
+
+
+
+
+
+
+
+
 {% endblock %}