Document how "link" will work

1 files changed, 52 insertions, 0 deletions

diff --git a/man1/future-ideas/new-module-system.1 b/man1/future-ideas/new-module-system.1
index 43b7d7c4a..cb1ffd092 100644
--- a/man1/future-ideas/new-module-system.1
+++ b/man1/future-ideas/new-module-system.1
@@ -280,3 +280,55 @@ If global is set to "true", or implied, then it removes the global copy\.
 If global is set to "false", or unset and the command is in a package
 folder with a copy of the package being removed, then it removes it from
 the local folder\.
+.
+.SS "Linking"
+When \fBnpm link\fR is run without any arguments in a package folder, then a
+symbolic link is created from that folder to \fBroot/<name>/LINK\fR\|\.
+Additionally, its package dependencies are installed to its
+\|\./node_modules folder as necessary\.
+.
+.P
+When \fBnpm link <name>\fR is run in another package folder, a symbolic
+link is created from \fBroot/<name>/LINK\fR to \fB\|\./node_modules/<name>\fR, and
+its dependencies are also installed if necessary\.  (Generally, it will
+not be necessary, as the package will already have its own node_modules
+folder containing its dependencies\.)
+.
+.P
+When publishing, linked package dependencies are resolved to their
+current state\.  It is assumed that the linked folder was linked for a
+reason, and may contain changes required for the proper functioning of
+the host program\.
+.
+.TP
+npm link use case
+.
+.IP "" 4
+.
+.nf
+# create a linked "request" package
+cd ~/projects/request
+npm link
+# now write a program that uses request
+mkdir \-p ~/projects/my\-program
+cd ~/projects/my\-program
+git init
+# do your git stuff\.\.\.
+npm init
+# enter some package\.json values
+# now we\'re ready to rock\.
+# use redis, but don\'t need bleeding edge\.
+npm install redis
+# use the linked copy of request
+npm link request
+# now any changes to ~/projects/request will
+# be immediately effective in my\-program when
+# I do require("request")
+.
+.fi
+.
+.IP "" 0
+.
+.TP
+link on Windows
+.Not sure how this will work\.  Maybe linking simply isn\'t possible?