Merge pull request #42 from dharmafly/development

Update the documentation #9

bin/elsewhere

@@ -46,9 +46,14 @@ function handler(req, res) {
   }
 
   // build the options object
-  options = {
-    strict:(query.strict !== undefined)
-  };
+  options = {}
+  if (query.strict !== undefined) {
+    options.strict = query.strict;
+  } else {
+    options.strict = false;
+  }
+
+  console.log(query.strict, options.strict);
 
   // build the object that the cache will cache against
   cacheKey = 'graph;';

docs/1. Overview.md

@@ -5,7 +5,7 @@ category: overview
 
 It does this by crawling a target url for `rel=me` [microformated][microformats] links. It then crawls those links for more `rel=me` links and so on, building a comprehensive graph as it goes.
 
-Elsewhere provides a JSON API that URL's can be easily queried against via client JavaScript. It can also be included as a [Node.js][node] module and used directly in your server projects.
+Elsewhere provides a JSON API that URL's can be easily queried against over a network. It can also be included as a [Node.js][node] module and used directly in your server projects.
 
 [node]: http://nodejs.org/
 [microformats]: http://microformats.org/wiki/rel-me

docs/2. How does it work.md

@@ -0,0 +1,15 @@
+---
+heading: "How does it work?"
+category: overview
+---
+Whether you use Elsewhere as a server or as part of your own node project, it works by you first providing it with a url.
+
+Elsewhere searches the page at this url for links, marked up with `rel=me`, linking to other pages. It then searches these subsequent pages for more links and so on.
+
+Any link found on any of these subsequent pages that links back to the original url, verifies the page. Any page that links to a verified page is then also marked as verified and so on.
+
+Any pages with these reciprical links to other pages in the graph can be reliably thought of belonging to the owner of the url you initially provided Elsewhere.
+
+Many profile pages do lack `rel=me` markup however and thus the reciprical links cannot be reliably established. As a result many legitimate profiles cannot be reliably marked as verified. When using the server you can choose to include these unverified links or not.
+
+Once Elsewhere has run out of links it returns with a graph representing the owner of your initial url, which you can then do what you like with.

docs/4. Changelog.md

@@ -0,0 +1,7 @@
+---
+category: overview
+---
+* v0.0.2
+    - Tweaks to the signature of the graph method. Various internal changes.
+* v0.0.1 
+    - First viable version of {{ site.PROJECT_NAME }}

docs/5. Requiring Elsewhere.md

@@ -0,0 +1,14 @@
+---
+category: reference
+---
+Elsewhere is available on [NPM][npm]. To install it just run:
+
+    npm install elsewhere
+
+Once you have it installed you may require it and interact with it using the `graph` method.
+
+    var elsewhere = require('elsewhere');
+
+    elsewhere.graph('http://premasagar.com');
+
+[npm]: https://npmjs.org/package/elsewhere

docs/6. The Graph Method.md

@@ -0,0 +1,30 @@
+---
+category: reference
+---
+The `graph` method takes the following three parameters.
+
+**url** This is the url that you wish to graph. The assumption is that it represents a person and has `rel=me` links to other urls also representing that person.
+
+**options** (optional) This object literal contains a few properties used to configure the graph. These properties are:
+
+- strict (boolean) `true` for strict mode, `false` otherwise. Strict mode only returns urls that link back to either the url provided in the first parameter or another url that does.
+
+- crawlLimit (integer) The number of links Elsewhere will follow without a successful verification before it abandons the chain. Defaults to 3.
+
+- stripDeeperLinks (boolean) If set to `true` then Elsewhere will discard links that share a domain with another link or links at a shallower level. E.g. plus.google.com/{id} is kept, while plus.google.com/{id}/posts is discarded.
+
+**callback** (optional) The function provided as this parameter will be called once the graph has been completely constructed. The callback is provided with one parameter: a completed `Graph` object.
+
+Here are some examples of valid calls to the graph method.
+
+    var options = {
+      strict: true
+    }
+
+    var callback = function (graph) {};
+
+    elsewhere.graph('http://premasagar.com', options, callback);
+
+    elsewhere.graph('http://chrisnewtn.com', callback);
+
+    elsewhere.graph('http://glennjones.net').then(callback);

docs/7. Global Configuration

@@ -0,0 +1,25 @@
+---
+category: reference
+---
+Instead of using a local `options` object each time you call the graph method, you can also set options in the global options object.
+
+Options shared between the global options object and local objects that are set via the global object act as defaults for each call to the graph method, any options that are then provided directly to the graph method via a local object will override those of the global object.
+
+The two options shared between the global options object and local objects are `crawlLimit` and `stripDeeperLinks`.
+
+**logging** (boolean) If set to `true` then Elsewhere will output the progress of the graph construction out to the terminal.
+
+**jsdomInstanceLimit** (integer) The maximum allowed number of concurrent JSDom instances. Set too low and graphs to be constructed too slowly, too high and you'll run out of memory. Defaults to 10.
+
+**crawlLimit** (integer) The number of links Elsewhere will follow without a successful verification before it abandons the chain. Defaults to 3.
+
+**stripDeeperLinks** (boolean) If set to `true` then Elsewhere will discard links that share a domain with another link or links at a shallower level. E.g. plus.google.com/{id} is kept, while plus.google.com/{id}/posts is discarded.
+
+**cacheLimit** (integer) The maximum amount of time (in milliseconds) that the constituent links of a graph are kept in memory for. If you are running the Elsewhere server then this figure also goes for complete graphs as well.
+
+If you are running Elsewhere as a server then you may set these options directly in `lib/options.js`. Here is some example usage of the options object:
+
+    elsewhere.options.jsdomInstanceLimit = 20;
+
+    elsewhere.options.logging = false;
+

lib/grapher.js

@@ -343,9 +343,16 @@ Grapher.prototype = {
  * at that same moment.
  */
 function graph (url, options, callback) {
-  var grapher  = new Grapher(url, options),
-      deferred = _.Deferred(),
-      promise  = deferred.promise();
+  var deferred = _.Deferred(),
+      promise  = deferred.promise(),
+      grapher;
+
+  if (arguments.length == 2 && _.isFunction(options)) {
+    callback = options;
+    options = {};
+  }
+
+  grapher = new Grapher(url, options);
 
   grapher.build(function (graph) {
     if (callback) callback(graph);

package.json

@@ -1,7 +1,7 @@
 {
   "author": "Dharmafly (dharmafly.com)",
   "name": "elsewhere",
-  "version": "0.0.1-6",
+  "version": "0.0.2",
   "repository": {
     "type": "git",
     "url": "git://github.com/dharmafly/elsewhere.git"

static/index.html

@@ -35,7 +35,7 @@ <h1>Elsewhere</h1>
   var url    = document.getElementById('url'),
       strict = document.getElementById('strict'),
       prog   = document.getElementById('prog'),
-      strict = strict.checked ? '&strict' : '',
+      strict = strict.checked ? '&strict=true' : '&strict=false',
       url    = location.href + '?url=' + encodeURIComponent(url.value) + strict,
       xhr    = new XMLHttpRequest();