Put directories.lib info back in the doc, and document the repository set

1 files changed, 89 insertions, 1 deletions

diff --git a/man/json.1 b/man/json.1
index f0cb2b2a5..98c41546d 100644
--- a/man/json.1
+++ b/man/json.1
@@ -84,8 +84,96 @@ and there was a file called \fB\|\./lib/baz\.js\fR, then require("foo/bar") woul
 the module defined in \fB\|\./lib/baz\.js\fR\|\.
 .
 .P
+Subfolders are supported, so you can do this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "modules" :
+  { "bar/baz" : "\./lib/bar/baz"
+  , "quux" : "\./quux"
+  }
+}
+.
+.fi
+.
+.IP "" 0
+.
+.P
+And then, doing \fBrequire("foo/bar/baz")\fR would return the module at \fB\|\./lib/bar/baz\fR
+in the foo package\.
+.
+.P
 Just like the \fBmain\fR script, the modules linked in this fashion will have their
-dependencies and paths set up properly by npm\.
+dependencies and paths set up properly by npm\. (In fact, "main" is just sugar
+around setting a module named "index"\.)
+.
+.SH "directories"
+The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a
+few ways that you can indicate the structure of your package using a \fBdirectories\fR
+hash\. If you look at npm\'s package\.json \fIhttp://registry\.npmjs\.org/npm/latest\fR,
+you\'ll see that it has directories for doc, lib, and man\.
+.
+.P
+In the future, this information may be used in other creative ways\.
+.
+.SS "directories\.lib"
+If you specify a "lib" directory, and do not supply a modules hash, then the lib folder
+will be walked and any \fI\|\.js or \fR\|\.node files found will be exposed as a default module
+hash\.  This is to provide backwards compatibility for packages that may have relied
+on this functionality when the lib folder was symlinked directly\.  Providing an explicit
+modules hash is encouraged over exposing the entire lib folder\.
+.
+.SH "repository"
+Specify the place where your code lives\. This is helpful for people who want to
+contribute, as well as perhaps maybe being the underpinning of some magical "track
+this package on git" feature someday maybe if somebody wants to write it ever\.
+.
+.P
+Do it like this:
+.
+.IP "" 4
+.
+.nf
+"repository" :
+  { "type" : "git"
+  , "url" : "http://github\.com/isaacs/npm\.git"
+  }
+"repository" :
+  { "type" : "svn"
+  , "url" : "http://v8\.googlecode\.com/svn/trunk/"
+  }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+The URL should be a publicly available (perhaps read\-only) url that can be handed
+directly to a VCS program without any modification\.  It should not be a url to an
+html project page that you put in your browser\.  It\'s for computers\.
+.
+.P
+Here are some examples of Doing It Wrong:
+.
+.IP "" 4
+.
+.nf
+WRONG!
+"repository" :
+  { "type" : "git"
+  , "url" : "git@github\.com:isaacs/npm\.git" <\-\- THIS IS PRIVATE!
+  }
+ALSO WRONG!
+"repository" :
+  { "type" : "git"
+  , "url" : "http://github\.com/isaacs/npm" <\-\- THIS IS WEBPAGE!
+  }
+.
+.fi
+.
+.IP "" 0
 .
 .SH "scripts"
 The "scripts" member is an object hash of script commands that are run