make doc

3 files changed, 78 insertions, 35 deletions

diff --git a/man1/faq.1 b/man1/faq.1
index d99cd12c3..c0b01e499 100644
--- a/man1/faq.1
+++ b/man1/faq.1
@@ -1,7 +1,7 @@
 .\" Generated with Ronnjs/v0.1
 .\" http://github.com/kapouer/ronnjs/
 .
-.TH "NPM\-FAQ" "1" "May 2011" "" ""
+.TH "NPM\-FAQ" "1" "July 2011" "" ""
 .
 .SH "NAME"
 \fBnpm-faq\fR \-\- Frequently Asked Questions
@@ -62,6 +62,23 @@ npm config set global true
 .P
 This is not recommended\.
 .
+.P
+Many things \fBwill not work\fR if you do this\.  Make sure you read and
+understand \fBnpm help config\fR and \fBnpm help global\fR before you complain
+about things being broken\.
+.
+.P
+When you realize what a mistake it was, do this to switch back:
+.
+.IP "" 4
+.
+.nf
+npm config delete global \-\-local
+.
+.fi
+.
+.IP "" 0
+.
 .SH "How do I list installed packages?"
 \fBnpm ls\fR
 .
diff --git a/man1/folders.1 b/man1/folders.1
index 65b692a23..7a532f198 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" "June 2011" "" ""
+.TH "NPM\-FOLDERS" "1" "July 2011" "" ""
 .
 .SH "NAME"
 \fBnpm-folders\fR \-\- Folder Structures Used by npm
@@ -26,6 +26,9 @@ Install it \fBlocally\fR if you\'re going to \fBrequire()\fR it\.
 .IP "\(bu" 4
 Install it \fBglobally\fR if you\'re going to run it on the command line\.
 .
+.IP "\(bu" 4
+If you need both, then install it in both places, or use \fBnpm link\fR\|\.
+.
 .IP "" 0
 .
 .SS "prefix Configuration"
@@ -129,14 +132,17 @@ prevented\.
 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:
+.TP
+Example
+.Consider this dependency graph:
 .
 .IP "" 4
 .
 .nf
 foo
++\-\- blerg@1\.2\.5
 +\-\- bar@1\.2\.3
+|   +\-\- blerg@1\.x (latest=1\.3\.7)
 |   +\-\- baz@2\.x
 |   |   `\-\- quux@3\.x
 |   |       `\-\- bar@1\.2\.3 (cycle)
@@ -157,15 +163,16 @@ In this case, we might expect a folder structure like this:
 .nf
 foo
 +\-\- node_modules
-    +\-\- bar (1\.2\.3) <\-\-\-[A]
+    +\-\- blerg (1\.2\.5) <\-\-\-[A]
+    +\-\- bar (1\.2\.3) <\-\-\-[B]
     |   +\-\- node_modules
-    |   |   `\-\- baz (2\.0\.2) <\-\-\-[B]
+    |   |   `\-\- baz (2\.0\.2) <\-\-\-[C]
     |   |       `\-\- node_modules
     |   |           `\-\- quux (3\.2\.0)
     |   `\-\- asdf (2\.3\.4)
-    `\-\- baz (1\.2\.3) <\-\-\-[C]
+    `\-\- baz (1\.2\.3) <\-\-\-[D]
         `\-\- node_modules
-            `\-\- quux (3\.2\.0) <\-\-\-[D]
+            `\-\- quux (3\.2\.0) <\-\-\-[E]
 .
 .fi
 .
@@ -176,29 +183,35 @@ Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are
 installed in foo\'s \fBnode_modules\fR folder\.
 .
 .P
-Bar [A] has dependencies on baz and asdf, so those are installed in bar\'s \fBnode_modules\fR folder\.  Because it depends on \fBbaz@2\.x\fR, it cannot re\-use
-the \fBbaz@1\.2\.3\fR installed in the parent \fBnode_modules\fR folder [C], and
-must install its own copy [B]\.
+Even though the latest copy of blerg is 1\.3\.7, foo has a specific
+dependency on version 1\.2\.5\.  So, that gets installed at [A]\.  Since the
+parent installation of blerg satisfie\'s bar\'s dependency on blerg@1\.x,
+it does not install another copy under [B]\.
+.
+.P
+Bar [B] also has dependencies on baz and asdf, so those are installed in
+bar\'s \fBnode_modules\fR folder\.  Because it depends on \fBbaz@2\.x\fR, it cannot
+re\-use the \fBbaz@1\.2\.3\fR installed in the parent \fBnode_modules\fR folder [D],
+and must install its own copy [C]\.
 .
 .P
 Underneath bar, the \fBbaz\->quux\->bar\fR dependency creates a cycle\.
-However, because \fBbar\fR is already in \fBquux\fR\'s ancestry [A], it does not
+However, because \fBbar\fR is already in \fBquux\fR\'s ancestry [B], it does not
 unpack another copy of bar into that folder\.
 .
 .P
-Underneath \fBfoo\->baz\fR [C], quux\'s [D] folder tree is empty, because its
-dependnecy on bar is satisfied by the parent folder copy installed at [A]\.
+Underneath \fBfoo\->baz\fR [D], quux\'s [E] folder tree is empty, because its
+dependency on bar is satisfied by the parent folder copy installed at [B]\.
 .
 .P
 For a graphical breakdown of what is installed where, use \fBnpm ls\fR\|\.
 .
 .SS "Publishing"
 Upon publishing, npm will look in the \fBnode_modules\fR 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\.
+the items there 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\.
+cannot be found elsewhere\.  See \fBnpm help json\fR for more information\.
diff --git a/man1/global.1 b/man1/global.1
index 65b692a23..7a532f198 100644
--- a/man1/global.1
+++ b/man1/global.1
@@ -1,7 +1,7 @@
 .\" Generated with Ronnjs/v0.1
 .\" http://github.com/kapouer/ronnjs/
 .
-.TH "NPM\-FOLDERS" "1" "June 2011" "" ""
+.TH "NPM\-FOLDERS" "1" "July 2011" "" ""
 .
 .SH "NAME"
 \fBnpm-folders\fR \-\- Folder Structures Used by npm
@@ -26,6 +26,9 @@ Install it \fBlocally\fR if you\'re going to \fBrequire()\fR it\.
 .IP "\(bu" 4
 Install it \fBglobally\fR if you\'re going to run it on the command line\.
 .
+.IP "\(bu" 4
+If you need both, then install it in both places, or use \fBnpm link\fR\|\.
+.
 .IP "" 0
 .
 .SS "prefix Configuration"
@@ -129,14 +132,17 @@ prevented\.
 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:
+.TP
+Example
+.Consider this dependency graph:
 .
 .IP "" 4
 .
 .nf
 foo
++\-\- blerg@1\.2\.5
 +\-\- bar@1\.2\.3
+|   +\-\- blerg@1\.x (latest=1\.3\.7)
 |   +\-\- baz@2\.x
 |   |   `\-\- quux@3\.x
 |   |       `\-\- bar@1\.2\.3 (cycle)
@@ -157,15 +163,16 @@ In this case, we might expect a folder structure like this:
 .nf
 foo
 +\-\- node_modules
-    +\-\- bar (1\.2\.3) <\-\-\-[A]
+    +\-\- blerg (1\.2\.5) <\-\-\-[A]
+    +\-\- bar (1\.2\.3) <\-\-\-[B]
     |   +\-\- node_modules
-    |   |   `\-\- baz (2\.0\.2) <\-\-\-[B]
+    |   |   `\-\- baz (2\.0\.2) <\-\-\-[C]
     |   |       `\-\- node_modules
     |   |           `\-\- quux (3\.2\.0)
     |   `\-\- asdf (2\.3\.4)
-    `\-\- baz (1\.2\.3) <\-\-\-[C]
+    `\-\- baz (1\.2\.3) <\-\-\-[D]
         `\-\- node_modules
-            `\-\- quux (3\.2\.0) <\-\-\-[D]
+            `\-\- quux (3\.2\.0) <\-\-\-[E]
 .
 .fi
 .
@@ -176,29 +183,35 @@ Since foo depends directly on bar@1\.2\.3 and baz@1\.2\.3, those are
 installed in foo\'s \fBnode_modules\fR folder\.
 .
 .P
-Bar [A] has dependencies on baz and asdf, so those are installed in bar\'s \fBnode_modules\fR folder\.  Because it depends on \fBbaz@2\.x\fR, it cannot re\-use
-the \fBbaz@1\.2\.3\fR installed in the parent \fBnode_modules\fR folder [C], and
-must install its own copy [B]\.
+Even though the latest copy of blerg is 1\.3\.7, foo has a specific
+dependency on version 1\.2\.5\.  So, that gets installed at [A]\.  Since the
+parent installation of blerg satisfie\'s bar\'s dependency on blerg@1\.x,
+it does not install another copy under [B]\.
+.
+.P
+Bar [B] also has dependencies on baz and asdf, so those are installed in
+bar\'s \fBnode_modules\fR folder\.  Because it depends on \fBbaz@2\.x\fR, it cannot
+re\-use the \fBbaz@1\.2\.3\fR installed in the parent \fBnode_modules\fR folder [D],
+and must install its own copy [C]\.
 .
 .P
 Underneath bar, the \fBbaz\->quux\->bar\fR dependency creates a cycle\.
-However, because \fBbar\fR is already in \fBquux\fR\'s ancestry [A], it does not
+However, because \fBbar\fR is already in \fBquux\fR\'s ancestry [B], it does not
 unpack another copy of bar into that folder\.
 .
 .P
-Underneath \fBfoo\->baz\fR [C], quux\'s [D] folder tree is empty, because its
-dependnecy on bar is satisfied by the parent folder copy installed at [A]\.
+Underneath \fBfoo\->baz\fR [D], quux\'s [E] folder tree is empty, because its
+dependency on bar is satisfied by the parent folder copy installed at [B]\.
 .
 .P
 For a graphical breakdown of what is installed where, use \fBnpm ls\fR\|\.
 .
 .SS "Publishing"
 Upon publishing, npm will look in the \fBnode_modules\fR 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\.
+the items there 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\.
+cannot be found elsewhere\.  See \fBnpm help json\fR for more information\.