First steps toward updating the docs

2015-10-16 00:25:49 -05:00 · 2015-10-16 00:25:49 -05:00 · 622b7486f7
parent 9ec1e9022d
commit 622b7486f7
16 changed files with 514 additions and 208 deletions
--- a/12
+++ b/12
@ -23,16 +23,8 @@ TAP		:= ./node_modules/.bin/tap
 #
 # Files
 #
-DOC_FILES	 =	client.md	\
-			dn.md		\
-			errors.md	\
-			examples.md	\
-			filters.md      \
-                        guide.md        \
-                        index.md        \
-                        persistent_search.md    \
-                        server.md
-
+DOC_FILES	:= $(shell find docs -name '*.md' -printf '%f\n')
+RESTDOWN_FLAGS	:= -b docs/branding/
 JS_FILES	:= $(shell find lib test -name '*.js') $(shell find bin -name 'ldapjs-*')
 JSL_CONF_NODE	 = tools/jsl.node.conf
 JSL_FILES_NODE   = $(JS_FILES)
--- a/deps/restdown
+++ b/deps/restdown
@ -1 +1 @@
-Subproject commit 14131f6b33bf45a04b4c66e388d0ce1f3e5b55ef
+Subproject commit 34a843cfce0ff988bf5073706882722a61036786
--- a/docs/branding/footer.html.in
+++ b/docs/branding/footer.html.in
@ -1,52 +1,46 @@
-<div id="footer">
-  <p class='copy'>Copyright &copy; 2011 <a href="https://github.com/mcavage">Mark Cavage</a></p>
-</div>
-</div> <!-- end of #main -->
-</div> <!-- end of #wrapper -->
 <script type="text/javascript" charset="utf-8">
-$(function () {
-    $("#toc").click(function(event) {
-        // This to ensure clicks in the #toc don't make it up to the
-        // button handler.
-        event.stopPropagation();
-    });
-    $("#toc a").click(function(event) {
-        $("#tocbutton").click();
-    })
-    $("#tocbutton").click(function(event) {
-        var target = $("#toc");
-        if (target.css("display") !== "block") {
-            $("body").bind("click.tocCloser", function(event) {
-                $("#tocbutton").click();
-                event.stopPropagation();
-            });
+$(function() {
+    var headerHeight = $("#header").height();
+    var offsets = [];
+    var current = -1;
+
+    function endpoint(scrollDistance) {
+        if (scrollDistance < offsets[0]) {
+            return -1;
        } else {
-            $("body").unbind("click.tocCloser");
+            for (var id = offsets.length; id > 0; id--) {
+                if (scrollDistance > offsets[id - 1]) {
+                    return id - 1;
+                    break;
+                }
+            }
        }
-        target.slideToggle(100);
-        event.stopPropagation();
+    }
+
+    $("h2").each(function(i) {
+        offsets.push($(this).offset().top - headerHeight)
    });

-    $("#api").click(function(event) {
-        // This to ensure clicks in the #api don't make it up to the
-        // button handler.
-        event.stopPropagation();
-    });
-    $("#api a").click(function(event) {
-        $("#apibutton").click();
-    })
-    $("#apibutton").click(function(event) {
-        var target = $("#api");
-        if (target.css("display") !== "block") {
-            $("body").bind("click.apiCloser", function(event) {
-                $("#apibutton").click();
-                event.stopPropagation();
-            });
-        } else {
-            $("body").unbind("click.apiCloser");
+    $("#content").append('<h2 class="fixed" style="display: none"><span>&nbsp;</span></h2>');
+    var fixed_h2 = $("h2.fixed");
+    var fixed_span = $("h2.fixed span");
+
+    $("#content").scroll(function() {
+        var scrollDistance = $("#content").attr('scrollTop');
+        var now = endpoint(scrollDistance);
+
+        if (now !== current) {
+            $("#sidebar li").removeClass("current");
+            current = now;
+            if (current < 0) {
+                fixed_h2.hide();
+            } else if (current >= 0) {
+                var heading = $($("h2 span")[current]).text();
+                $("#sidebar a[href|=#" + heading.replace(' ', '-') + "]").parent().addClass("current");
+                fixed_span.text(heading);
+                fixed_h2.show();
+            }
        }
-        target.slideToggle(100);
-        event.stopPropagation();
    });
 });
 </script>
--- a/docs/branding/header.html.in
+++ b/docs/branding/header.html.in
@ -1,57 +1,32 @@
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <title>%(title)s</title>
-  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
-  <link rel="stylesheet" type="text/css" href="%(mediaroot)s/css/style.css">
-  %(doc_style)s
-  <script type="text/javascript" src="media/js/jquery-1.4.2.min.js"></script>
-<script type="text/javascript">
-  var _gaq = _gaq || [];
-  _gaq.push(['_setAccount', 'UA-25326304-1']);
-  _gaq.push(['_trackPageview']);
-
-  (function() {
-    var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
-    ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
-    var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
-  })();
-</script>
+    <title>%(title)s</title>
+    <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+    <link rel="stylesheet" type="text/css" href="%(mediaroot)s/css/restdown.css">
+    <script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/jquery/1.4.2/jquery.min.js"></script>
 </head>
 <body>
-<div id="wrapper">
-<div id="main">
-<div id="fadeout"></div>
 <div id="header">
-  <span id="logo">
-    <a id="homelink" href="http://ldapjs.org">ldapjs</a>
-  </span>
-
-  <a class="navbutton" href="guide.html">Guide</a>
-
-  <span id="apibox">
-    <span id="apibutton" class="navbutton">API</span>
-    <div id="api" class="popup" style="display: none">
-      <ul>
-        <li><div><a href="server.html">server</a></div></li>
-        <li><div><a href="client.html">client</a></div></li>
-        <li><div><a href="dn.html">dn</a></div></li>
-        <li><div><a href="filters.html">filters</a></div></li>
-        <li><div><a href="errors.html">errors</a></div></li>
-        <li><div><a href="examples.html">examples</a></div></li>
-      </ul>
-    </div>
-  </span>
-
-  <span id="tocbox">
-    <span id="tocbutton" class="navbutton">Page Contents</span>
-    <div id="toc" class="popup" style="display: none">
-      %(toc_html)s
-    </div>
-  </span>
-
-  <a id="githubfork" href="http://github.com/mcavage/node-ldapjs">
-    <img src="https://a248.e.akamai.net/assets.github.com/img/abad93f42020b733148435e2cd92ce15c542d320/687474703a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677265656e5f3030373230302e706e67"
-         alt="Fork me on GitHub">
-  </a>
+    <h1>%(title)s Documentation</h1>
+</div>
+<div id="sidebar">
+
+<div>Sections</div>
+<span>
+<ul>
+<li><div><a href="index.html">Home</a></div></li>
+<li><div><a href="guide.html">Guide</a></div></li>
+<li><div><a href="examples.html">Examples</a></div></li>
+<li><div><a href="client.html">Client API</a></div></li>
+<li><div><a href="server.html">Server API</a></div></li>
+<li><div><a href="dn.html">DN API</a></div></li>
+<li><div><a href="filters.html">Filters API</a></div></li>
+<li><div><a href="errors.html">Error API</a></div></li>
+</ul>
+</span>
+
+<div>Contents</div>
+</span>
+%(toc_html)s
 </div>
--- a/docs/branding/media/css/restdown.css
+++ b/docs/branding/media/css/restdown.css
@ -0,0 +1,325 @@
+
+/* ---- general styles */
+
+body {
+  font: 13px "Lucida Grande", "Lucida Sans Unicode", arial, sans-serif;
+  line-height: 1.53846; /* 20px */
+  color: #4a3f2d;
+}
+
+:focus {
+  outline: 0;
+}
+
+h1,h2,h3 {
+  font-weight:normal;
+}
+
+h3{
+  margin-bottom:0;
+}
+
+ul, li {
+  margin:0px;
+  padding:0px;
+}
+
+ul {
+  margin-left:40px;
+}
+
+ul > li {
+  list-style:disc;
+  list-style-position:inside;
+  margin:10px 0px;
+}
+
+hr {
+  border:none;
+  width:98%;
+  margin-left:-10px;
+  border-top:1px solid #CCCCCC;
+  border-bottom:1px solid #FFFFFF;
+}
+
+code,
+pre {
+  border:1px solid #CCCCCC;
+  background:#F2F0EE;
+  -webkit-border-radius:2px;
+  -moz-border-radius:2px;
+  border-radius:2px;
+  white-space:pre-wrap;
+}
+code {
+  padding: 0 0.2em;
+}
+pre {
+  margin: 1em 0;
+  padding: .75em;
+  overflow: auto;
+  padding:10px 1.2em;
+  margin-top:0;
+  margin-bottom:20px;
+}
+pre code  {
+  border: medium none;
+  padding: 0;
+}
+a code {
+  text-decoration: underline;
+}
+
+a {
+  color:#FD6512;
+  text-decoration:none;
+}
+
+h4 {
+  font-size: 85%;
+  margin: 0;
+  padding: 0;
+  line-height: 1em;
+  display: inline;
+}
+
+
+
+/* ---- custom classes */
+
+pre.shell,
+pre.shell code {
+  background:#444;
+  color:#fff;
+  border-width:0px;
+}
+pre.shell code::before {
+  content: '$ ';
+  display: inline;
+}
+
+
+/* ---- header and sidebar */
+
+#header {
+  background:#C3BDB3;
+  background:#1C313C;
+  height:66px;
+  left:0px;
+  position:absolute;
+  top:0px;
+  width:100%;
+  z-index:1;
+  font-size:0.7em;
+}
+
+#header h1 {
+  width: 424px;
+  height: 35px;
+  display:block;
+  background: url(../img/logo.svg) no-repeat;
+  line-height:2.1em;
+  padding:0;
+  padding-left:140px;
+  margin-top:18px;
+  margin-left:20px;
+  color:white;
+  text-transform: uppercase;
+}
+
+#sidebar {
+  background-color:#EDEBEA;
+  bottom:0px;
+  left:0px;
+  overflow:auto;
+  padding:20px 0px 0px 15px;
+  position:absolute;
+  top:66px;
+  width:265px;
+  z-index:1;
+}
+
+#content {
+  top:64px;
+  bottom:0px;
+  right:0px;
+  left:290px;
+  padding:20px 30px 400px;
+  position:absolute;
+  overflow:auto;
+  z-index:0;
+}
+
+#sidebar .vertical_divider {
+  background-color:#FFFFFF;
+  bottom:0px;
+  position:absolute;
+  top:0px;
+  right:0px;
+  width:1px;
+}
+
+#sidebar h1 {
+  font-size:1.2em;
+  padding:0px;
+  margin-top:15px;
+  margin-bottom:3px;
+}
+
+#sidebar ul {
+  margin:3px 0 10px 0;
+}
+
+#sidebar ul ul {
+  margin:3px 0 5px 10px;
+}
+
+#sidebar li {
+  margin:0;
+  padding:0;
+  font-size:0.9em;
+}
+
+#sidebar li,
+#sidebar li a {
+  color:#5C5954;
+  list-style:none;
+  padding:1px 0px 1px 2px;
+}
+
+#sidebar li span.verb {
+  color:#aaa;
+  padding:2px 3px 0px;
+  width:30px;
+  display:block;
+  float:left;
+  font-size:9px;
+  font-family:verdana;
+  -moz-border-radius:3px;
+  -webkit-border-radius:3px;
+  margin-left:0px;
+  margin-right:5px;
+}
+
+#sidebar li.current {
+  background-repeat: no-repeat;
+  background-position:right;
+}
+
+
+/* ---- intro */
+
+.intro {
+  color:#29231A;
+  padding: 22px 25px;
+  background: #EDEBEA;
+  -webkit-border-radius: 5px;
+  -moz-border-radius: 5px;
+  -o-border-radius: 5px;
+  border-radius: 5px;
+  margin-bottom:40px;
+}
+.intro pre.base {
+  background:#444;
+  color:#29231A;
+  color:#fff;
+  border-color:#fff;
+  font-size:1.5em;
+}
+.intro h1 {
+  color: #1C313C;
+}
+.intro h3 {
+  margin: 5px 0px 3px;
+  font-size: 100%;
+  font-weight: bold;
+}
+.intro ul {
+  list-style-type:disc;
+  padding-left:20px;
+  margin-left:0;
+}
+.intro ul li{
+  margin:0;
+}
+.intro p {
+  padding-left:20px;
+  margin: 5px 0px 3px;
+}
+
+
+
+h2 {
+  overflow: auto;
+  margin-top: 60px;
+  border-top: 2px solid #979592;
+  z-index: 3;
+}
+h1 + h2 {
+  margin-top: 0px;
+}
+
+h2.fixed {
+  position:fixed;
+  margin-top: 0;
+  border-top:none;
+  right:45px;
+  top:66px;
+}
+
+h2 span {
+  background: #979592;
+  float:right;
+  color:#fff;
+  margin:0;
+  margin-left:3px;
+  padding:0.3em 0.7em;
+  font-size: 0.55em;
+  word-spacing: 0.8em;  /* separate verb from path */
+  color:#fff;
+}
+
+
+
+
+/*---- print media */
+
+@media print {
+  body { background:white; color:black; margin:0; }
+  #sidebar {
+    display: none;
+  }
+  #content {
+    position: relative;
+    padding: 5px;
+    left: 0px;
+    top: 0px;
+  }
+  h1, h2, h4 {
+    page-break-after: avoid;
+  }
+  pre {
+    page-break-inside: avoid;
+  }
+}
+
+/* tables still need cellspacing="0" in the markup */
+table {
+  border-collapse:collapse; border-spacing:0;
+  margin: 20px 0;
+}
+th,
+td {
+  border: solid #aaa;
+  border-width: 1px 0;
+  line-height: 23px;
+  padding: 0 12px;
+  text-align: left;
+  vertical-align: text-bottom;
+}
+th {
+  border-collapse: separate;
+}
+tbody tr:nth-child(odd) {
+  background-color: #f2f0ee;
+}
--- a/docs/branding/media/img/logo.svg
+++ b/docs/branding/media/img/logo.svg
@ -0,0 +1 @@
+<svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="125" height="34.1" viewBox="0 0 146.25 39.96"><defs><path d="M-2.21-3.96h150v45.93h-150z"/><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><clipPath><use xlink:href="#c-4" overflow="visible"/></clipPath></defs><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><g clip-path="url(#b-8)" fill="#f60"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use xlink:href="#c-4" overflow="visible" x="0" y="0" width="100" height="100"/></clipPath><path d="m15.74 31.29c8.61 0 15.6-6.98 15.6-15.59C31.34 7.08 24.35 0.1 15.74 0.1 7.13 0.1 0.14 7.08 0.14 15.7c0 8.61 6.98 15.6 15.6 15.6" style="fill-rule:evenodd;fill:#f60"/><path d="m12.96 7.35c0-0.32 0.26-0.59 0.59-0.59l4.38 0c0.33 0 0.59 0.26 0.59 0.59l0 5.57 5.57 0c0.33 0 0.59 0.26 0.59 0.59l0 4.38c0 0.33-0.26 0.59-0.59 0.59l-5.57 0 0 5.57c0 0.33-0.26 0.59-0.59 0.59l-4.37 0c-0.32 0-0.59-0.26-0.59-0.59l0-5.57-5.57 0c-0.32 0-0.59-0.26-0.59-0.59l0-4.37c0-0.32 0.26-0.59 0.59-0.59l5.57 0z" style="fill-rule:evenodd;fill:#fff"/></g><g clip-path="url(#b)" fill="#fff"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use height="100" width="100" y="0" x="0" overflow="visible" xlink:href="#c"/></clipPath><path d="m35.84 25.26c1.22 0.94 2.63 1.81 4.52 1.81 2.87 0 3.62-1.73 3.62-4.01l0-19.96 3.11 0 0 16.27c0 1.42 0 2.95-0.08 4.36-0.16 3.77-2.08 5.97-6.52 5.97-3.06 0-5.31-1.26-6.21-2.24zm29.51-5.7c0-4.72-1.37-8.02-5.19-8.02-3.73 0-5.42 3.14-5.42 7.39 0 3.89 0.79 8.49 5.27 8.49 3.73 0 5.35-3.57 5.35-7.86M60.41 9.14c2.71 0 8.06 0.87 8.06 9.75 0 7.66-3.81 10.89-8.72 10.89-4.99 0-8.06-3.38-8.06-10.45 0-8.13 4.83-10.18 8.72-10.18m26.88 19.3 0-18.74-2.99 0 0 11.71c0 2.71-1.81 4.6-4.79 4.6-4.17 0-4.44-2.28-4.44-5.27l0-11.04-3.06 0 0 11.87c0 4.48 2.16 6.09 5.5 6.45-1.93 1.26-4.32 3.54-4.32 6.72 0 3.03 1.93 4.95 5.93 4.95 4.17 0 6.68-2 7.66-5.82 0.35-1.38 0.51-3.69 0.51-5.42m-7.86 8.88c3.58 0 4.83-3.1 4.83-7.39l0-3.42c-4.72 1.97-8.13 4.09-8.13 7.82 0 1.93 1.14 2.99 3.3 2.99M99.94 9.14c-5.97 0-9.12 4.79-9.12 10.61 0 5.86 2.59 10.02 8.72 10.02 3.14 0 5.42-1.41 6.41-2.24l-1.18-2c-0.75 0.55-2.4 1.81-5.03 1.81-4.16 0-5.74-3.38-5.89-6.6l1.02 0.04c3.81 0 10.81-0.94 10.81-6.76 0-2.91-2.08-4.87-5.74-4.87m-0.16 2.28c-4.2 0-5.82 3.97-5.93 7.07l0.79 0.04c2.67 0 8.17-0.63 8.17-4.17 0-1.85-1.26-2.95-3.03-2.95m13.01 17.8 0-12.81c0-2.36 2.28-4.83 5.31-4.83 3.3 0 3.93 2.36 3.93 5.27l0 12.38 3.07 0 0-13.32c0-4.48-2.2-6.76-6.25-6.76-2.56 0-4.83 1.18-6.33 3.38l-0.35-2.83-2.63 0 0.2 2.95 0 16.58 3.07 0zm16.82-27.31 0 21.97c0 2.87 0.16 5.9 5.38 5.9 1.57 0 3.3-0.51 4.44-1.3l-0.9-2.04c-0.67 0.39-1.65 0.94-2.99 0.94-1.85 0-2.87-0.82-2.87-3.42l0-11.63 5.58 0 0-2.63-5.58 0 0-7.78zm12.22 1.8c0 1.14 0.91 1.99 2 1.99 1.08 0 1.99-0.85 1.99-1.99 0-1.12-0.91-1.97-1.99-1.97-1.09 0-2 0.85-2 1.97m0.36 0c0-0.95 0.71-1.68 1.64-1.68 0.92 0 1.63 0.73 1.63 1.68 0 0.97-0.71 1.7-1.63 1.7-0.93 0-1.64-0.73-1.64-1.7m0.86 1.17 0.36 0 0-1 0.38 0 0.63 1 0.39 0-0.66-1.02c0.35-0.04 0.61-0.21 0.61-0.63 0-0.44-0.26-0.66-0.81-0.66l-0.9 0 0 2.32zm0.36-2.02 0.48 0c0.24 0 0.51 0.05 0.51 0.36 0 0.37-0.29 0.38-0.61 0.38l-0.38 0z" clip-path="url(#d)" style="fill-rule:evenodd;fill:#fff"/></g></svg>
--- a/docs/client.md
+++ b/docs/client.md
@ -1,15 +1,12 @@
 ---
 title: Client API | ldapjs
-markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
+markdown2extras: tables
 ---

 # ldapjs Client API

 This document covers the ldapjs client API and assumes that you are familiar
-with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
+with LDAP. If you're not, read the [guide](guide.html) first.

 # Create a client

@ -25,18 +22,22 @@ that this will not use the LDAP TLS extended operation, but literally an SSL
 connection to port 636, as in LDAP v2). The full set of options to create a
 client is:

-||url|| a valid LDAP url.||
-||socketPath|| If you're running an LDAP server over a Unix Domain Socket, use this.||
-||log|| You can optionally pass in a bunyan instance the client will use to acquire a logger.  The client logs all messages at the `trace` level.||
-||timeout||How long the client should let operations live for before timing out. Default is Infinity.||
-||connectTimeout||How long the client should wait before timing out on TCP connections. Default is up to the OS.||
-||tlsOptions||Additional [options](http://nodejs.org/api/tls.html#tls_tls_connect_port_host_options_callback) passed to the TLS connection layer when connecting via `ldaps://`||
-
+|Attribute      |Description                                                |
+|---------------|-----------------------------------------------------------|
+|url            |A valid LDAP URL (proto/host/port only)                    |
+|socketPath     |Socket path if using AF\_UNIX sockets                      |
+|log            |Bunyan logger instance (Default: built-in instance)        |
+|timeout        |How long the client should let operations live for before timing out (Default: Infinity)|
+|connectTimeout |How long the client should wait before timing out on TCP connections (Default: OS default)|
+|tlsOptions     |Additional options passed to the TLS connection layer when connecting via `ldaps://` (See: The TLS docs for node.js)|
+|idleTimeout    |Seconds after last activity before client emits idle event|
+|strictDN       |Force strict DN parsing for client methods (Default is true)|

 ## Connection management

 As LDAP is a stateful protocol (as opposed to HTTP), having connections torn
-down from underneath you is difficult to deal with.
+down from underneath you is can be difficult to deal with.  Several mechanisms
+have been provided to mitigate this trouble.


 ## Common patterns
@ -49,8 +50,11 @@ Almost every operation has the callback form of `function(err, res)` where err
 will be an instance of an `LDAPError` (you can use `instanceof` to switch).
 You probably won't need to check the `res` parameter, but it's there if you do.

+
+
+
 # bind
-`bind(dn, password, controls,callback)`
+`bind(dn, password, controls, callback)`

 Performs a bind operation against the LDAP server.

@ -166,7 +170,7 @@ server.  A couple points with this client API:

 * There is no ability to set "keep old dn."  It's always going to flag the old
 dn to be purged.
-* The client code will automagically figure out if the request is a "new
+* The client code will automatically figure out if the request is a "new
 superior" request ("new superior" means move to a different part of the tree,
 as opposed to just renaming the leaf).

@ -192,12 +196,14 @@ Like every other operation, `base` is a DN string.
 Options can be a string representing a valid LDAP filter or an object
 containing the following fields:

-||scope||One of `base`, `one`, or `sub`. Defaults to `base`.||
-||filter||A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`.||
-||attributes||attributes to select and return (if these are set, the server will return *only* these attributes). Defaults to the empty set, which means all attributes. You can provide a string if you want a single attribute or an array of string for one or many.||
-||attrsOnly||boolean on whether you want the server to only return the names of the attributes, and not their values.  Borderline useless.  Defaults to false.||
-||sizeLimit||the maximum number of entries to return. Defaults to 0 (unlimited).||
-||timeLimit||the maximum amount of time the server should take in responding, in seconds. Defaults to 10.  Lots of servers will ignore this.||
+|Attribute  |Description                                        |
+|-----------|---------------------------------------------------|
+|scope      |One of `base`, `one`, or `sub`. Defaults to `base`.|
+|filter     |A string version of an LDAP filter (see below), or a programatically constructed `Filter` object. Defaults to `(objectclass=*)`.|
+|attributes |attributes to select and return (if these are set, the server will return *only* these attributes). Defaults to the empty set, which means all attributes. You can provide a string if you want a single attribute or an array of string for one or many.|
+|attrsOnly  |boolean on whether you want the server to only return the names of the attributes, and not their values.  Borderline useless.  Defaults to false.|
+|sizeLimit  |the maximum number of entries to return. Defaults to 0 (unlimited).|
+|timeLimit  |the maximum amount of time the server should take in responding, in seconds. Defaults to 10.  Lots of servers will ignore this.|

 Responses from the `search` method are an `EventEmitter` where you will get a
 notification for each `searchEntry` that comes back from the server.  You will
@ -271,6 +277,24 @@ The `not` character is represented as a `!`, the `or` as a single pipe `|`.
 It gets a little bit complicated, but it's actually quite powerful, and lets you
 find almost anything you're looking for.

+# starttls
+`starttls(options, controls, callback)`
+
+Attempt to secure existing LDAP connection via STARTTLS.
+
+Example:
+
+    var opts = {
+      ca: [fs.readFileSync('mycacert.pem')]
+    };
+
+    client.starttls(opts, function(err, res) {
+      assert.ifError(err);
+
+      // Client communication now TLS protected
+    });
+
+
 # unbind
 `unbind(callback)`

--- a/docs/dn.md
+++ b/docs/dn.md
@ -1,15 +1,11 @@
 ---
 title: DN API | ldapjs
-markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
 ---

 # ldapjs DN API

 This document covers the ldapjs DN API and assumes that you are familiar
-with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
+with LDAP. If you're not, read the [guide](guide.html) first.

 DNs are LDAP distinguished names, and are composed of a set of RDNs (relative
 distinguished names).  [RFC2253](http://www.ietf.org/rfc/rfc2253.txt) has the
@ -81,6 +77,33 @@ argument. `dn` can be a string or a DN.
 Returns a DN object that is the direct parent of `this`.  If there is no parent
 this can return `null` (e.g. `parseDN('o=example').parent()` will return null).

+
+## format(options)
+
+Convert a DN object to string according to specified formatting options.  These
+options are divided into two types.  Preservation Options use data recorded
+during parsing to preserve details of the original DN. Modification options
+alter string formatting defaults.  Preservation options _always_ take
+precedence over Modification Options.
+
+Preservation Options:
+
+ - `keepOrder`: Order of multi-value RDNs.
+ - `keepQuote`: RDN values which were quoted will remain so.
+ - `keepSpace`: Leading/trailing spaces will be output.
+ - `keepCase`: Parsed attribute name will be output instead of lowercased version.
+
+Modification Options:
+
+- `upperName`: RDN names will be uppercased instead of lowercased.
+- `skipSpace`: Disable trailing space after RDN separators
+
+## setFormat(options)
+
+Sets the default `options` for string formatting when `toString` is called.
+It accepts the same parameters as `format`.
+
+
 ## toString()

 Returns the string representation of `this`.
--- a/docs/errors.md
+++ b/docs/errors.md
@ -1,15 +1,11 @@
 ---
 title: Errors API | ldapjs
-markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
 ---

 # ldapjs Errors API

 This document covers the ldapjs errors API and assumes that you are familiar
-with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
+with LDAP. If you're not, read the [guide](guide.html) first.

 All errors in the ldapjs framework extend from an abstract error type called
 `LDAPError`. In addition to the properties listed below, all errors will have
--- a/docs/examples.md
+++ b/docs/examples.md
@ -1,9 +1,5 @@
 ---
 title: Examples | ldapjs
-markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
 ---

 # ldapjs Examples
--- a/docs/filters.md
+++ b/docs/filters.md
@ -1,15 +1,11 @@
 ---
 title: Filters API | ldapjs
-markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
 ---

 # ldapjs Filters API

 This document covers the ldapjs filters API and assumes that you are familiar
-with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
+with LDAP. If you're not, read the [guide](guide.html) first.

 LDAP search filters are really the backbone of LDAP search operations, and
 ldapjs tries to get you in "easy" with them if your dataset is small, and also
@ -28,17 +24,6 @@ All Filters in the ldapjs framework extend from `Filter`, which wil have the
 property `type` available; this will return a string name for the filter, and
 will be one of:

-||equal||an `EqualityFilter`||
-||present||a `PresenceFilter`||
-||substring||a `SubstringFilter`||
-||ge||a `GreaterThanEqualsFilter`||
-||le||a `LessThanEqualsFilter`||
-||and||an `AndFilter`||
-||or||an `OrFilter`||
-||not||a `NotFilter`||
-||approx||an `ApproximateMatchFilter` (quasi-supported in ldapjs)||
-||ext||an `ExtensibleMatchFilter` (not supported in ldapjs)||
-
 # parseFilter(filterString)

 Parses an [RFC2254](http://www.ietf.org/rfc/rfc2254.txt) filter string into an
--- a/docs/guide.md
+++ b/docs/guide.md
@ -1,9 +1,6 @@
 ---
 title: LDAP Guide | ldapjs
-markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
+markdown2extras: tables
 ---

 # LDAP Guide
@ -135,7 +132,7 @@ since we haven't added any support in yet, but go ahead and try it anyway:
    $ ldapsearch -H ldap://localhost:1389 -x -b "o=myhost" objectclass=*

 Before we go any further, note that the complete code for the server we are
-about to build up is on the [examples](http://ldapjs.org/examples.html) page.
+about to build up is on the [examples](examples.html) page.

 ## Bind

@ -237,13 +234,15 @@ for a moment to explain an /etc/passwd record.

 The sample record above maps to:

-||jsmith||user name.||
-||x||historically this contained the password hash, but that's usually in /etc/shadow now, so you get an 'x'.||
-||1001||the unix numeric user id.||
-||1000||the unix numeric group id. (primary).||
-||'Joe Smith,...'||the "gecos," which is a description, and is usually a comma separated list of contact details.||
-||/home/jsmith||the user's home directory.||
-||/bin/sh||the user's shell.||
+|Field              |Description                        |
+|-------------------|-----------------------------------|
+|jsmith             |Username                           |
+|x                  |Placeholder for password hash      |
+|1001               |Numeric UID                        |
+|1000               |Numeric Primary GID                |
+|'Joe Smith,...'    |DisplayName                        |
+|/home/jsmith       |Home directory                     |
+|/bin/sh            |Shell                              |

 Let's write some handlers to parse that and transform it into an LDAP search
 record (note, you'll need to add `var fs = require('fs');` at the top of the
@ -629,8 +628,8 @@ And then run the following command:
 # Where to go from here

 The complete source code for this example server is available in
-[examples](/examples.html).  Make sure to read up on the [server](/server.html)
-and [client](/client.html) APIs.  If you're looking for a "drop in" solution,
+[examples](examples.html).  Make sure to read up on the [server](server.html)
+and [client](client.html) APIs.  If you're looking for a "drop in" solution,
 take a look at [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak).

 [Mozilla](https://wiki.mozilla.org/Mozilla_LDAP_SDK_Programmer%27s_Guide/Understanding_LDAP)
--- a/docs/index.md
+++ b/docs/index.md
@ -1,9 +1,6 @@
 ---
 title: ldapjs
-markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
+markdown2extras: tables
 ---

 <div id="indextagline">
@ -15,7 +12,7 @@ Reimagining <a href="http://tools.ietf.org/html/rfc4510" id="indextaglink">LDAP<
 ldapjs is a pure JavaScript, from-scratch framework for implementing
 [LDAP](http://tools.ietf.org/html/rfc4510) clients and servers in
 [Node.js](http://nodejs.org).  It is intended for developers used to interacting
-with HTTP services in node and [express](http://expressjs.com).
+with HTTP services in node and [restify](http://restify.com).

    var ldap = require('ldapjs');

@ -57,22 +54,25 @@ that you can build LDAP over anything you want, not just traditional databases.

    $ npm install ldapjs

-If you're new to LDAP, check out the [guide](/guide.html).  Otherwise, the
+If you're new to LDAP, check out the [guide](guide.html).  Otherwise, the
 API documentation is:

-||[server](/server.html)||Reference for implementing LDAP servers.||
-||[client](/client.html)||Reference for implementing LDAP clients.||
-||[dn](/dn.html)||API reference for the DN class.||
-||[filters](/filters.html)||API reference for LDAP search filters.||
-||[errors](/errors.html)||Listing of all ldapjs Error objects.||
-||[examples](/examples.html)||Collection of sample/getting started code.||
+
+|Section                    |Content                                    |
+|---------------------------|-------------------------------------------|
+|[Server API](server.html)  |Reference for implementing LDAP servers.   |
+|[Client API](client.html)  |Reference for implementing LDAP clients.   |
+|[DN API](dn.html)          |API reference for the DN class.            |
+|[Filter API](filters.html) |API reference for LDAP search filters.     |
+|[Error API](errors.html)   |Listing of all ldapjs Error objects.       |
+|[Examples](examples.html)  |Collection of sample/getting started code. |

 # More information

-||License||[MIT](http://opensource.org/licenses/mit-license.php)||
-||Code||[mcavage/node-ldapjs](https://github.com/mcavage/node-ldapjs)||
-||node.js version||>=0.6||
-||Twitter||[@mcavage](http://twitter.com/mcavage)||
+- License:[MIT](http://opensource.org/licenses/mit-license.php)
+- Code: [mcavage/node-ldapjs](https://github.com/mcavage/node-ldapjs)
+- node.js version: >=0.8
+- Twitter: [@pfmooney](http://twitter.com/pfmooney)

 # What's not in the box?

--- a/docs/server.md
+++ b/docs/server.md
@ -1,15 +1,12 @@
 ---
 title: Server API | ldapjs
 markdown2extras: wiki-tables
-logo-color: green
-logo-font-family: google:Aldrich, Verdana, sans-serif
-header-font-family: google:Aldrich, Verdana, sans-serif
 ---

 # ldapjs Server API

 This document covers the ldapjs server API and assumes that you are familiar
-with LDAP. If you're not, read the [guide](http://ldapjs.org/guide.html) first.
+with LDAP. If you're not, read the [guide](guide.html) first.

 # Create a server

@ -47,8 +44,7 @@ Emitted when the server closes.

 ## Listening for requests

-The LDAP server API wraps up and mirrors the node
-[listen](http://nodejs.org/docs/v0.4.11/api/net.html#server.listen) family of
+The LDAP server API wraps up and mirrors the node.js `server.listen` family of
 APIs.

 After calling `listen`, the property `url` on the server object itself will be
@ -66,7 +62,7 @@ Example:

 Begin accepting connections on the specified port and host. If the host is
 omitted, the server will accept connections directed to any IPv4 address
-(INADDR_ANY).
+(INADDR\_ANY).

 This function is asynchronous. The last parameter callback will be called when
 the server has been bound.
@ -90,7 +86,7 @@ calls invoked on it. Additionally, it must be set non-blocking; try

 # Routes

-The LDAP server API is meant to be the LDAP-equivalent of the express/sinatra
+The LDAP server API is meant to be the LDAP-equivalent of the express/restify
 paradigm of programming.  Essentially every method is of the form
 `OP(req, res, next)` where OP is one of bind, add, del, etc.  You can chain
 handlers together by calling `next()` and ordering your functions in the
@ -112,8 +108,8 @@ caching, etc. that need to be placed in an object.

 For example [ldapjs-riak](https://github.com/mcavage/node-ldapjs-riak) is a
 complete implementation of the LDAP protocol over
-[Riak](http://www.basho.com/products_riak_overview.php).  Getting an LDAP
-server up with riak looks like:
+[Riak](https://github.com/basho/riak).  Getting an LDAP server up with riak
+looks like:

    var ldap = require('ldapjs');
    var ldapRiak = require('ldapjs-riak');
@ -155,7 +151,7 @@ All request objects have the `dn` getter on it, which is "context-sensitive"
 and returns the point in the tree that the operation wants to operate on.  The
 LDAP protocol itself sadly doesn't define operations this way, and has a unique
 name for just about every op.  So, ldapjs calls it `dn`.  The DN object itself
-is documented at [DN](/dn.html).
+is documented at [DN](dn.html).

 All requests have an optional array of `Control` objects.  `Control` will have
 the properties `type` (string), `criticality` (boolean), and optionally, a
@ -175,7 +171,7 @@ identify the request/connection pair in logs (includes the LDAP messageID).

 All response objects will have an `end` method on them.  By default, calling
 `res.end()` with no arguments will return SUCCESS (0x00) to the client
-(with the exception of `compare` which will return COMPARE_TRUE (0x06)).  You
+(with the exception of `compare` which will return COMPARE\_TRUE (0x06)).  You
 can pass in a status code to the `end()` method to return an alternate status
 code.

@ -186,8 +182,8 @@ and error message for you.
 ## Errors

 ldapjs includes an exception hierarchy that directly corresponds to the RFC list
-of error codes.  The complete list is documented in [errors](/errors.html). But
-the paradigm is something defined like CONSTRAINT_VIOLATION in the RFC would be
+of error codes.  The complete list is documented in [errors](errors.html). But
+the paradigm is something defined like CONSTRAINT\_VIOLATION in the RFC would be
 `ConstraintViolationError` in ldapjs.  Upon calling `next(new LDAPError())`,
 ldapjs will _stop_ calling your handler chain.  For example:

@ -330,7 +326,7 @@ Whether to return only the names of attributes, and not the values.  Defaults to

 ### filter

-The [filter](/filters.html) object that the client requested.  Notably this has
+The [filter](filters.html) object that the client requested.  Notably this has
 a `matches()` method on it that you can leverage.  For an example of
 introspecting a filter, take a look at the ldapjs-riak source.

--- a/tools/mk/Makefile.deps
+++ b/tools/mk/Makefile.deps
@ -40,5 +40,5 @@ $(JSSTYLE_EXEC): | deps/jsstyle/.git
 # restdown
 #
 RESTDOWN_EXEC	?= deps/restdown/bin/restdown
-RESTDOWN	?= python2.6 $(RESTDOWN_EXEC)
+RESTDOWN	?= python $(RESTDOWN_EXEC)
 $(RESTDOWN_EXEC): | deps/restdown/.git
--- a/tools/mk/Makefile.targ
+++ b/tools/mk/Makefile.targ
@ -239,8 +239,8 @@ DOC_MEDIA_FILES_BUILD := $(DOC_MEDIA_FILES:%=$(DOC_BUILD)/media/%)
 #
 .PHONY: docs
 docs:							\
-    $(DOC_FILES:%.restdown=$(DOC_BUILD)/%.html)		\
-    $(DOC_FILES:%.restdown=$(DOC_BUILD)/%.json)		\
+    $(DOC_FILES:%.md=$(DOC_BUILD)/%.html)		\
+    $(DOC_FILES:%.md=$(DOC_BUILD)/%.json)		\
    $(DOC_MEDIA_FILES_BUILD)

 #
@ -248,16 +248,16 @@ docs:							\
 # files in DOC_BUILD are up to date.
 #
 .PRECIOUS:					\
-    $(DOC_FILES:%.restdown=docs/%.html)		\
-    $(DOC_FILES:%.restdown=docs/%json)
+    $(DOC_FILES:%.md=docs/%.html)		\
+    $(DOC_FILES:%.md=docs/%json)

 #
 # We do clean those intermediate files, as well as all of DOC_BUILD.
 #
 CLEAN_FILES +=					\
    $(DOC_BUILD)				\
-    $(DOC_FILES:%.restdown=docs/%.html)		\
-    $(DOC_FILES:%.restdown=docs/%.json)
+    $(DOC_FILES:%.md=docs/%.html)		\
+    $(DOC_FILES:%.md=docs/%.json)

 #
 # Before installing the files, we must make sure the directories exist. The |
@ -270,7 +270,7 @@ $(DOC_MEDIA_FILES_BUILD): | $(DOC_MEDIA_DIRS_BUILD)
 $(DOC_BUILD)/%: docs/% | $(DOC_BUILD)
 	$(CP) $< $@

-docs/%.json docs/%.html: docs/%.restdown | $(DOC_BUILD) $(RESTDOWN_EXEC)
+docs/%.json docs/%.html: docs/%.md | $(DOC_BUILD) $(RESTDOWN_EXEC)
 	$(RESTDOWN) $(RESTDOWN_FLAGS) -m $(DOC_BUILD) $<

 $(DOC_BUILD):
				`@ -0,0 +1 @@`
				<svg xmlns:svg="http://www.w3.org/2000/svg" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" version="1.1" width="125" height="34.1" viewBox="0 0 146.25 39.96"><defs><path d="M-2.21-3.96h150v45.93h-150z"/><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><clipPath><use xlink:href="#c-4" overflow="visible"/></clipPath></defs><clipPath><use xlink:href="#a" overflow="visible"/></clipPath><g clip-path="url(#b-8)" fill="#f60"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use xlink:href="#c-4" overflow="visible" x="0" y="0" width="100" height="100"/></clipPath><path d="m15.74 31.29c8.61 0 15.6-6.98 15.6-15.59C31.34 7.08 24.35 0.1 15.74 0.1 7.13 0.1 0.14 7.08 0.14 15.7c0 8.61 6.98 15.6 15.6 15.6" style="fill-rule:evenodd;fill:#f60"/><path d="m12.96 7.35c0-0.32 0.26-0.59 0.59-0.59l4.38 0c0.33 0 0.59 0.26 0.59 0.59l0 5.57 5.57 0c0.33 0 0.59 0.26 0.59 0.59l0 4.38c0 0.33-0.26 0.59-0.59 0.59l-5.57 0 0 5.57c0 0.33-0.26 0.59-0.59 0.59l-4.37 0c-0.32 0-0.59-0.26-0.59-0.59l0-5.57-5.57 0c-0.32 0-0.59-0.26-0.59-0.59l0-4.37c0-0.32 0.26-0.59 0.59-0.59l5.57 0z" style="fill-rule:evenodd;fill:#fff"/></g><g clip-path="url(#b)" fill="#fff"><defs><path d="m-2.21-3.96 150 0 0 45.93-150 0z"/></defs><clipPath><use height="100" width="100" y="0" x="0" overflow="visible" xlink:href="#c"/></clipPath><path d="m35.84 25.26c1.22 0.94 2.63 1.81 4.52 1.81 2.87 0 3.62-1.73 3.62-4.01l0-19.96 3.11 0 0 16.27c0 1.42 0 2.95-0.08 4.36-0.16 3.77-2.08 5.97-6.52 5.97-3.06 0-5.31-1.26-6.21-2.24zm29.51-5.7c0-4.72-1.37-8.02-5.19-8.02-3.73 0-5.42 3.14-5.42 7.39 0 3.89 0.79 8.49 5.27 8.49 3.73 0 5.35-3.57 5.35-7.86M60.41 9.14c2.71 0 8.06 0.87 8.06 9.75 0 7.66-3.81 10.89-8.72 10.89-4.99 0-8.06-3.38-8.06-10.45 0-8.13 4.83-10.18 8.72-10.18m26.88 19.3 0-18.74-2.99 0 0 11.71c0 2.71-1.81 4.6-4.79 4.6-4.17 0-4.44-2.28-4.44-5.27l0-11.04-3.06 0 0 11.87c0 4.48 2.16 6.09 5.5 6.45-1.93 1.26-4.32 3.54-4.32 6.72 0 3.03 1.93 4.95 5.93 4.95 4.17 0 6.68-2 7.66-5.82 0.35-1.38 0.51-3.69 0.51-5.42m-7.86 8.88c3.58 0 4.83-3.1 4.83-7.39l0-3.42c-4.72 1.97-8.13 4.09-8.13 7.82 0 1.93 1.14 2.99 3.3 2.99M99.94 9.14c-5.97 0-9.12 4.79-9.12 10.61 0 5.86 2.59 10.02 8.72 10.02 3.14 0 5.42-1.41 6.41-2.24l-1.18-2c-0.75 0.55-2.4 1.81-5.03 1.81-4.16 0-5.74-3.38-5.89-6.6l1.02 0.04c3.81 0 10.81-0.94 10.81-6.76 0-2.91-2.08-4.87-5.74-4.87m-0.16 2.28c-4.2 0-5.82 3.97-5.93 7.07l0.79 0.04c2.67 0 8.17-0.63 8.17-4.17 0-1.85-1.26-2.95-3.03-2.95m13.01 17.8 0-12.81c0-2.36 2.28-4.83 5.31-4.83 3.3 0 3.93 2.36 3.93 5.27l0 12.38 3.07 0 0-13.32c0-4.48-2.2-6.76-6.25-6.76-2.56 0-4.83 1.18-6.33 3.38l-0.35-2.83-2.63 0 0.2 2.95 0 16.58 3.07 0zm16.82-27.31 0 21.97c0 2.87 0.16 5.9 5.38 5.9 1.57 0 3.3-0.51 4.44-1.3l-0.9-2.04c-0.67 0.39-1.65 0.94-2.99 0.94-1.85 0-2.87-0.82-2.87-3.42l0-11.63 5.58 0 0-2.63-5.58 0 0-7.78zm12.22 1.8c0 1.14 0.91 1.99 2 1.99 1.08 0 1.99-0.85 1.99-1.99 0-1.12-0.91-1.97-1.99-1.97-1.09 0-2 0.85-2 1.97m0.36 0c0-0.95 0.71-1.68 1.64-1.68 0.92 0 1.63 0.73 1.63 1.68 0 0.97-0.71 1.7-1.63 1.7-0.93 0-1.64-0.73-1.64-1.7m0.86 1.17 0.36 0 0-1 0.38 0 0.63 1 0.39 0-0.66-1.02c0.35-0.04 0.61-0.21 0.61-0.63 0-0.44-0.26-0.66-0.81-0.66l-0.9 0 0 2.32zm0.36-2.02 0.48 0c0.24 0 0.51 0.05 0.51 0.36 0 0.37-0.29 0.38-0.61 0.38l-0.38 0z" clip-path="url(#d)" style="fill-rule:evenodd;fill:#fff"/></g></svg>