make doc

5 files changed, 255 insertions, 26 deletions

diff --git a/man1/config.1 b/man1/config.1
index 9f4146597..c8035deea 100644
--- a/man1/config.1
+++ b/man1/config.1
@@ -336,7 +336,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to show the description in \fBnpm search\fR
+Show the description in \fBnpm search\fR
 .
 .SS "dev"
 .
@@ -349,7 +349,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to install \fBdev\-dependencies\fR along with packages\.
+Install \fBdev\-dependencies\fR along with packages\.
 .
 .P
 Note that \fBdev\-dependencies\fR are also installed if the \fBnpat\fR flag is
@@ -406,7 +406,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\.  See \fBnpm help global\fR for more on the differences in behavior\.
+Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\.  See \fBnpm help folders\fR for more on the differences in behavior\.
 .
 .IP "\(bu" 4
 packages are installed into the \fBprefix/node_modules\fR folder, instead of the
@@ -552,7 +552,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to show extended information in \fBnpm ls\fR
+Show extended information in \fBnpm ls\fR
 .
 .SS "node\-version"
 .
@@ -578,7 +578,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to run tests on installation and report results to the \fBnpaturl\fR\|\.
+Run tests on installation and report results to the \fBnpaturl\fR\|\.
 .
 .SS "npaturl"
 .
@@ -631,7 +631,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to output parseable results from commands that write to
+Output parseable results from commands that write to
 standard output\.
 .
 .SS "prefix"
@@ -672,8 +672,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Set to some truish value to rebuild bundled dependencies after
-installation\.
+Rebuild bundled dependencies after installation\.
 .
 .SS "registry"
 .
@@ -688,6 +687,19 @@ Type: url
 .P
 The base URL of the npm package registry\.
 .
+.SS "rollback"
+.
+.IP "\(bu" 4
+Default: true
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
+.
+.P
+Remove failed installs\.
+.
 .SS "searchopts"
 .
 .IP "\(bu" 4
diff --git a/man1/folders.1 b/man1/folders.1
index d07337381..e6a660173 100644
--- a/man1/folders.1
+++ b/man1/folders.1
@@ -1,7 +1,7 @@
 .\" Generated with Ronnjs/v0.1
 .\" http://github.com/kapouer/ronnjs/
 .
-.TH "NPM\-FOLDERS" "1" "March 2011" "" ""
+.TH "NPM\-FOLDERS" "1" "April 2011" "" ""
 .
 .SH "NAME"
 \fBnpm-folders\fR \-\- Folder Structures Used by npm
@@ -22,7 +22,7 @@ When it is not set, it uses the root of the current package, or the
 current working directory if not in a package already\.
 .
 .SS "Node Modules"
-Packages are droped into the \fBnode_modules\fR folder under the \fBprefix\fR\|\.
+Packages are dropped into the \fBnode_modules\fR folder under the \fBprefix\fR\|\.
 When installing locally, this means that you can \fBrequire("packagename")\fR to load its main module, or \fBrequire("packagename/path/to/sub/module")\fR to load other modules\.
 .
 .P
diff --git a/man1/get.1 b/man1/get.1
index 9f4146597..c8035deea 100644
--- a/man1/get.1
+++ b/man1/get.1
@@ -336,7 +336,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to show the description in \fBnpm search\fR
+Show the description in \fBnpm search\fR
 .
 .SS "dev"
 .
@@ -349,7 +349,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to install \fBdev\-dependencies\fR along with packages\.
+Install \fBdev\-dependencies\fR along with packages\.
 .
 .P
 Note that \fBdev\-dependencies\fR are also installed if the \fBnpat\fR flag is
@@ -406,7 +406,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\.  See \fBnpm help global\fR for more on the differences in behavior\.
+Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\.  See \fBnpm help folders\fR for more on the differences in behavior\.
 .
 .IP "\(bu" 4
 packages are installed into the \fBprefix/node_modules\fR folder, instead of the
@@ -552,7 +552,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to show extended information in \fBnpm ls\fR
+Show extended information in \fBnpm ls\fR
 .
 .SS "node\-version"
 .
@@ -578,7 +578,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to run tests on installation and report results to the \fBnpaturl\fR\|\.
+Run tests on installation and report results to the \fBnpaturl\fR\|\.
 .
 .SS "npaturl"
 .
@@ -631,7 +631,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to output parseable results from commands that write to
+Output parseable results from commands that write to
 standard output\.
 .
 .SS "prefix"
@@ -672,8 +672,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Set to some truish value to rebuild bundled dependencies after
-installation\.
+Rebuild bundled dependencies after installation\.
 .
 .SS "registry"
 .
@@ -688,6 +687,19 @@ Type: url
 .P
 The base URL of the npm package registry\.
 .
+.SS "rollback"
+.
+.IP "\(bu" 4
+Default: true
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
+.
+.P
+Remove failed installs\.
+.
 .SS "searchopts"
 .
 .IP "\(bu" 4
diff --git a/man1/global.1 b/man1/global.1
new file mode 100644
index 000000000..e6a660173
--- /dev/null
+++ b/man1/global.1
@@ -0,0 +1,193 @@
+.\" Generated with Ronnjs/v0.1
+.\" http://github.com/kapouer/ronnjs/
+.
+.TH "NPM\-FOLDERS" "1" "April 2011" "" ""
+.
+.SH "NAME"
+\fBnpm-folders\fR \-\- Folder Structures Used by npm
+.
+.SH "DESCRIPTION"
+npm puts various things on your computer\.  That\'s its job\.
+.
+.P
+This document will tell you what it puts where\.
+.
+.SS "prefix Configuration"
+The \fBprefix\fR config defaults to node\'s \fBprocess\.installPrefix\fR\|\.  On most
+systems, this is \fB/usr/local\fR\|\.
+.
+.P
+When the \fBglobal\fR flag is set, npm installs things into this prefix\.
+When it is not set, it uses the root of the current package, or the
+current working directory if not in a package already\.
+.
+.SS "Node Modules"
+Packages are dropped into the \fBnode_modules\fR folder under the \fBprefix\fR\|\.
+When installing locally, this means that you can \fBrequire("packagename")\fR to load its main module, or \fBrequire("packagename/path/to/sub/module")\fR to load other modules\.
+.
+.P
+If you wish to install node modules globally which can be loaded via \fBrequire()\fR from anywhere, then add the \fBprefix/node_modules\fR folder to
+your NODE_PATH environment variable\.
+.
+.SS "Executables"
+When in global mode, executables are linked into \fBprefix/bin\fR\|\.
+.
+.P
+When in local mode, executables are linked into \fBprefix/node_modules/\.bin\fR\|\.
+.
+.SS "Man Pages"
+When in global mode, man pages are linked into \fBprefix/share/man\fR\|\.
+.
+.P
+When in local node, man pages are not installed\.
+.
+.SS "Cache"
+See \fBnpm help cache\fR\|\.  Cache files are stored in \fB~/\.npm\fR on Posix, or \fB~/npm\-cache\fR on Windows\.
+.
+.P
+This is controlled by the \fBcache\fR configuration param\.
+.
+.SS "Temp Files"
+Temporary files are stored by default in the folder specified by the \fBtmp\fR config, which defaults to either the TMPDIR environment
+variable, or \fB/tmp\fR\|\.
+.
+.P
+Temp files are given a unique folder under this root for each run of the
+program, and are deleted upon successful exit\.
+.
+.SH "More Information"
+When you run \fBnpm install foo@1\.2\.3\fR it downloads and builds the
+package, and then, if there is a package\.json file in the current
+working directory, it copies it to \fB$PWD/node_modules/foo\fR, so that your
+current package will get it when you do \fBrequire("foo")\fR\|\.
+.
+.P
+When this is done, it also installs all of foo\'s dependencies to \fB\|\./node_modules/foo/node_modules/\fR, so that it will get its dependencies
+appropriately when it calls \fBrequire()\fR\|\.  If foo depends on bar, and bar
+depends on baz, then there will also be a \fB\|\./node_modules/foo/node_modules/bar/node_modules/baz\fR, and so on\.
+.
+.P
+If there is not a package\.json in the current working directory, then
+npm walks up the working dir parent paths looking for a package\.json,
+indicating the root of a package, or a node_modules folder,
+indicating an npm package deployment location, and then take the party to that
+location\.  This behavior may be suppressed by setting the \fBseek\-root\fR
+config value to false\.
+.
+.P
+If no package root is found, then a global installation is performed\.
+The global installation may be supressed by setting the \fBglobal\fR
+configuration to false, in which case, the install will fail\.
+.
+.SS "Global Installation"
+If the \fBglobal\fR configuration is set to true, or if it is not explicitly
+set false and no suitable node_modules folder was found, then npm will
+install packages "globally"\.
+.
+.P
+This means that the module contents are symlinked (or, on windows,
+copied) from \fBroot/<name>/<version>/package\fR to \fBroot/node_modules/<name>\fR\|\.
+.
+.SS "Cycles, Conflicts, and Folder Parsimony"
+Cycles are handled using the property of node\'s module system that it
+walks up the directories looking for node\fImodules folders\.  So, at every
+stage, if a package is already installed in an ancestor node\fRmodules
+folder, then it is not installed at the current location\.
+.
+.P
+Consider the case above, where \fBfoo \-> bar \-> baz\fR\|\.  Imagine if, in
+addition to that, baz depended on bar, so you\'d have: \fBfoo \-> bar \-> baz \-> bar \-> baz \.\.\.\fR\|\.  However, since the folder
+structure is: foo/node\fImodules/bar/node\fRmodules/baz, there\'s no need to
+put another copy of bar into \.\.\./baz/node\fImodules, since when it calls
+require("bar"), it will get the copy that is installed in
+foo/node\fRmodules/bar\.
+.
+.P
+This shortcut is only used if the exact same
+version would be installed in multiple nested node_modules folders\.  It
+is still possible to have \fBa/node_modules/b/node_modules/a\fR if the two
+"a" packages are different versions\.  However, without repeating the
+exact same package multiple times, an infinite regress will always be
+prevented\.
+.
+.P
+Another optimization can be made by installing dependencies at the
+highest level possible, below the localized "target" folder\.
+.
+.P
+For example, consider this dependency graph:
+.
+.IP "" 4
+.
+.nf
+foo
++\-\- bar@1\.2\.3
+|   +\-\- baz@2\.x
+|   |   `\-\- quux@3\.x
+|   |       `\-\- bar@1\.2\.3 (cycle)
+|   `\-\- asdf@*
+`\-\- baz@1\.2\.3
+    `\-\- quux@3\.x
+        `\-\- bar
+.
+.fi
+.
+.IP "" 0
+.
+.P
+In this case, we might expect a folder structure like this:
+.
+.IP "" 4
+.
+.nf
+foo
++\-\- node_modules
+    +\-\- bar (1\.2\.3)
+    |   +\-\- node_modules
+    |   |   `\-\- baz (2\.0\.2)
+    |   |       `\-\- node_modules
+    |   |           `\-\- quux (3\.2\.0)
+    |   `\-\- asdf (2\.3\.4)
+    `\-\- baz (1\.2\.3)
+        `\-\- node_modules
+            `\-\- quux (3\.2\.0)
+                `\-\- node_modules
+                    `\-\- bar (1\.2\.3)
+                        `\-\- node_modules
+                            `\-\- asdf (2\.3\.4)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are
+installed in foo\'s node_modules folder\.
+.
+.P
+Bar has dependencies on baz and asdf, so those are installed in bar\'s
+node\fImodules folder\.  Baz has a dependency on quux, so that is installed
+in its node\fRmodules folder\.
+.
+.P
+Underneath bar, the \fBbaz\->quux\->bar\fR dependency creates a cycle\.
+However, because \fBbar\fR is already in \fBquux\fR\'s ancestry, it does not
+unpack another copy of bar into that folder\.
+.
+.P
+Similarly, underneath \fBfoo\->baz\fR, the same cycle is gradually prevented
+because \fBbar\fR\'s \fBquux\fR dependency is satisfied by its parent folder\.
+.
+.P
+For a graphical breakdown of what is installed where, use \fBnpm ls\fR\|\.
+.
+.SS "Publishing"
+Upon publishing, npm will look in the node_modules folder\.  If any of
+the items there are on the "dependencies" or "devDependencies" list,
+and are not in the \fBbundledDependencies\fR array, then they will not be
+included in the package tarball\.
+.
+.P
+This allows a package maintainer to install all of their dependencies
+(and dev dependencies) locally, but only re\-publish those items that
+cannot be found elsewhere\.
diff --git a/man1/set.1 b/man1/set.1
index 9f4146597..c8035deea 100644
--- a/man1/set.1
+++ b/man1/set.1
@@ -336,7 +336,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to show the description in \fBnpm search\fR
+Show the description in \fBnpm search\fR
 .
 .SS "dev"
 .
@@ -349,7 +349,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to install \fBdev\-dependencies\fR along with packages\.
+Install \fBdev\-dependencies\fR along with packages\.
 .
 .P
 Note that \fBdev\-dependencies\fR are also installed if the \fBnpat\fR flag is
@@ -406,7 +406,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\.  See \fBnpm help global\fR for more on the differences in behavior\.
+Operates in "global" mode, so that packages are installed into the \fBprefix\fR folder instead of the current working directory\.  See \fBnpm help folders\fR for more on the differences in behavior\.
 .
 .IP "\(bu" 4
 packages are installed into the \fBprefix/node_modules\fR folder, instead of the
@@ -552,7 +552,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to show extended information in \fBnpm ls\fR
+Show extended information in \fBnpm ls\fR
 .
 .SS "node\-version"
 .
@@ -578,7 +578,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to run tests on installation and report results to the \fBnpaturl\fR\|\.
+Run tests on installation and report results to the \fBnpaturl\fR\|\.
 .
 .SS "npaturl"
 .
@@ -631,7 +631,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Whether or not to output parseable results from commands that write to
+Output parseable results from commands that write to
 standard output\.
 .
 .SS "prefix"
@@ -672,8 +672,7 @@ Type: Boolean
 .IP "" 0
 .
 .P
-Set to some truish value to rebuild bundled dependencies after
-installation\.
+Rebuild bundled dependencies after installation\.
 .
 .SS "registry"
 .
@@ -688,6 +687,19 @@ Type: url
 .P
 The base URL of the npm package registry\.
 .
+.SS "rollback"
+.
+.IP "\(bu" 4
+Default: true
+.
+.IP "\(bu" 4
+Type: Boolean
+.
+.IP "" 0
+.
+.P
+Remove failed installs\.
+.
 .SS "searchopts"
 .
 .IP "\(bu" 4