make doc

6 files changed, 109 insertions, 69 deletions

diff --git a/man/config.1 b/man/config.1
index e0fc6df4d..183a6e584 100644
--- a/man/config.1
+++ b/man/config.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "NPM\-CONFIG" "1" "May 2010" "" ""
+.TH "NPM\-CONFIG" "1" "July 2010" "" ""
 .
 .SH "NAME"
 \fBnpm\-config\fR \- Manage the npm configuration file
@@ -113,7 +113,7 @@ Default: https://registry\.npmjs\.org/
 .P
 The base URL of the npm package registry\.
 .
-.SS "auth"
+.SS "_auth"
 A base\-64 encoded "user:pass" pair\. This is created by npm\-adduser(1)\.
 .
 .P
@@ -123,19 +123,14 @@ If your config file is ever corrupted, you can set this manually by doing:
 .
 .nf
 
-npm config set auth $(echo \-n "my\-user\-name:my\-password" | base64)
-    npm config set username my\-user\-name
-    npm config set email me@email\.com
+npm adduser
 .
 .fi
 .
 .IP "" 0
 .
-.P
-\fBNOTE\fR: This is not encoded in any kind of security sense\. It\'s just base\-64 encoded strictly so that it can be sent along the wire with HTTP Basic authentication\.
-.
-.SS "authCrypt"
-If crypto\.Cipher is available, and you have some private keys in \fB$HOME/\.ssh\fR, then npm will encrypt your "auth" config before saving to the \.npmrc file, and will decrypt the "authCrypt" config when it reads the \.npmrc file\.
+.SS "_authCrypt"
+If crypto\.Cipher is available, and you have some private keys in \fB$HOME/\.ssh\fR, then npm will encrypt your "\fIauth" config before saving to the \.npmrc file, and will decrypt the "\fRauthCrypt" config when it reads the \.npmrc file\.
 .
 .SS "tag"
 Default: stable
diff --git a/man/folders.1 b/man/folders.1
index 70a63f97b..707b25d9c 100644
--- a/man/folders.1
+++ b/man/folders.1
@@ -1,13 +1,13 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "NPM\-FOLDERS" "1" "May 2010" "" ""
+.TH "NPM\-FOLDERS" "1" "July 2010" "" ""
 .
 .SH "NAME"
 \fBnpm\-folders\fR \- Folder Structures Used by npm
 .
 .SH "DESCRIPTION"
-Everything lives in the \fBroot\fR setting\. This defaults to \fB$HOME/\.node_libraries/\fR\. I\'d like to be able to override it, but that\'s not possible yet\.
+Everything lives in the \fBroot\fR setting\. Check \fBnpm help config\fR for more on configuration options\.
 .
 .P
 \fBroot/\.npm/foo\fR is where the stuff for package \fBfoo\fR would go\.
@@ -16,10 +16,7 @@ Everything lives in the \fBroot\fR setting\. This defaults to \fB$HOME/\.node_li
 \fBroot/\.npm/foo/1\.0\.0/package\fR the contents of the tarball containing foo version 1\.0\.0
 .
 .P
-\fBroot/\.npm/foo/1\.0\.0/main\.js\fR Generated file that exports the \fBmain\fR module in foo\.
-.
-.P
-\fBroot/\.npm/foo/1\.0\.0/lib\fR symlink to the \fBlib\fR dir in foo\.
+\fBroot/\.npm/foo/1\.0\.0/main\.js\fR Generated file that exports the \fBmain\fR module in foo\. This is a shim, not a symbolic link, so that relative paths will work appropriately\.
 .
 .P
 \fBroot/\.npm/foo/active\fR symlink to the active version\.
@@ -29,9 +26,3 @@ Everything lives in the \fBroot\fR setting\. This defaults to \fB$HOME/\.node_li
 .
 .P
 \fBroot/foo\.js\fR symlink to \fB\.npm/foo/active/main\.js\fR
-.
-.P
-\fBroot/foo\fR symlink to \fB\.npm/foo/active/lib\fR
-.
-.P
-\fBroot/foo\-1\.0\.0\fR symlink to \fB\.npm/foo/1\.0\.0/lib\fR
diff --git a/man/help.1 b/man/help.1
index 76256e43d..fb321eb3c 100644
--- a/man/help.1
+++ b/man/help.1
@@ -14,8 +14,81 @@ npm help <section>
 .
 .fi
 .
+.SH "DESCRIPTION"
+\fB<section>\fR is one of: activate adduser build cache coding\-style config deactivate developers folders help install json link list ln ls npm publish registry restart rm scripts start stop tag test uninstall unpublish
+.
+.SH "12\-second Intro"
+You probably got npm because you want to install stuff\.
+.
+.P
+Use \fBnpm install blerg\fR to install the latest version of "blerg"\. Check out \fBnpm help install\fR for more info\. It can do a lot of stuff\.
+.
+.P
+Use the \fBnpm ls\fR command to show everything that\'s available\. Looking for express\-related modules? \fBnpm ls express\fR\. Looking for the latest express? \fBnpm ls express latest\fR\. (The arguments are just simple greps\.) And of course, \fBnpm help ls\fR will tell you more\.
+.
+.P
+Use \fBnpm ls installed\fR to show everything you\'ve installed\.
+.
+.SH "Where to go for help"
+Come bug isaacs in irc://freenode\.net#node\.js\. He\'ll ask you to copy the npm output to a pastie or gist, and perhaps to post an issue if it\'s a new bug\.
+.
 .P
-Where \fB<section>\fR is one of: activate adduser build cache coding\-style config deactivate developers folders help install json link list ln ls npm publish registry restart rm scripts start stop tag test uninstall unpublish
+Failing that, report the issue:
+.
+.TP
+web
+\fIhttp://github\.com/isaacs/npm/issues\fR
+.
+.TP
+email
+\fInpm\-@googlegroups\.com\fR
+.
+.P
+If you ask something that\'s answered by this doc, you may be told to RTFM\. So, save yourself some time and read it now\.
+.
+.SH "Configs"
+Use the \fBnpm config\fR command to manage how npm does stuff and where it puts things\. It stores your configs in the \fB~/\.npmrc\fR file\. Check \fBnpm help config\fR for more info on that, if you care\.
 .
-.SH "Todo"
-It\'d be nice if this page was automatically generated so that it stays up to date better\.
+.P
+You can override any config for just a single command by doing \fB\-\-configname value\fR on the command line\.
+.
+.SH "Developers"
+If you\'re using npm to develop and publish your code, check out the following topics:
+.
+.TP
+json
+Make a package\.json file\. The "json" help doc will tell you what to put in it\.
+.
+.TP
+link
+For linking your current working code into Node\'s path, so that you don\'t have to reinstall every time you make a change\. Use "npm link" to do this\.
+.
+.TP
+install
+It\'s a good idea to install things if you don\'t need the symbolic link\. Especially, installing other peoples code from the registry is done via "npm install"\.
+.
+.TP
+adduser
+Use the \fBnpm adduser\fR command to add a user account for the npm registry, or to authorize yourself on a new machine\. If you forget your password, send an email to \fInpm\-@googlegroups\.com\fR and we\'ll delete your account so you can recreate it\.
+.
+.TP
+publish
+Use the \fBnpm publish\fR command to upload your code to the registry, so that other people can install it easily\.
+.
+.SH "Contributing"
+Patches welcome!
+.
+.TP
+code
+Read through \fBnpm help coding\-style\fR if you plan to submit code\. You don\'t have to agree with it, but you do have to follow it\.
+.
+.TP
+docs
+If you find an error in the documentation, edit the appropriate markdown file in the "doc" folder\. If you have the "ronn" gem installed, then you can \fBmake doc\fR to build the man page, but this is not necessary for your patch to be accepted\.
+.
+.TP
+tests
+The tests are pretty limited\. It would be great to perhaps use something like expresso or vows\.
+.
+.P
+Contributors are listed in npm\'s \fBpackage\.json\fR file\.
diff --git a/man/json.1 b/man/json.1
index f5f0735e7..924ab6aa9 100644
--- a/man/json.1
+++ b/man/json.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "NPM\-JSON" "1" "June 2010" "" ""
+.TH "NPM\-JSON" "1" "July 2010" "" ""
 .
 .SH "NAME"
 \fBnpm\-json\fR \- Specifics of npm\'s package\.json handling
@@ -77,7 +77,7 @@ The "scripts" member is an object hash of script commands that are run at variou
 See \fBnpm help scripts\fR to find out more about writing package scripts\.
 .
 .SH "dependencies"
-Dependencies are specified with a simple hash of package name to version range\. The version range is EITHER a string with has one or more space\-separated descriptors\.
+Dependencies are specified with a simple hash of package name to version range\. The version range is EITHER a string with has one or more space\-separated descriptors, OR a range like "fromVersion \- toVersion"
 .
 .P
 Version range descriptors may be any of the following styles, where "version" is a semver compatible version identifier\.
diff --git a/man/npm.1 b/man/npm.1
index 5f1b9a4b5..6a2a90aa6 100644
--- a/man/npm.1
+++ b/man/npm.1
@@ -18,26 +18,10 @@ npm <command> [args]
 npm is a little package manager for the Node javascript library\.
 .
 .P
-See npm\-help(1) for more details about specific commands\.
+Run \fBnpm help\fR for help\. That\'s probably what you meant to do\.
 .
-.P
-npm supports a very basic argument parser\. For any of the settings in npm\-config(1), you can set them explicitly for a single command by doing:
-.
-.IP "" 4
-.
-.nf
-
-npm \-\-key val <command>
-.
-.fi
-.
-.IP "" 0
-.
-.P
-If you are a package maintainer, please investigate the documentation at npm\-json(1), npm\-publish(1), and npm\-tag(1) sections first\. See npm\-folders(1) section to see how you can leverage npm\'s functionality for your own purposes\.
-.
-.SH "STATUS: beta"
-The core functionality is there\. You can publish, tag, and install\. It handles dependencies relatively smartly\.
+.SH "STATUS: Useful Beta"
+The core functionality is there\. It works\.
 .
 .P
 Please use this software\. It will cut you occasionally\. Let me know when you find a rough edge, and I\'ll sand it down for you\.
@@ -45,7 +29,7 @@ Please use this software\. It will cut you occasionally\. Let me know when you f
 .P
 I appreciate your sense of adventure\.
 .
-.SH "Principles"
+.SH "PRINCIPLES"
 Put the files where they need to be so that node can find them using the methods it already uses\.
 .
 .P
@@ -61,24 +45,26 @@ Sync with habits that are already in use\.
 Packages should be maintained by their authors, not by the package manager author\.
 .
 .P
-Run it on node\. Cuz a node package manager should be written in evented javascript\.
+Steer clear of dependency hell\.
 .
-.SH "Contributing"
-If you\'re interested in helping, that\'s awesome! Please fork this project, implement some of the things on the todo list, or fix an issue, or even just write or edit some documentation\. You have no idea just how thankful I\'ll be\.
+.SH "BUGS"
+Plenty\. Luckily, npm is actively maintained as of this writing\.
 .
 .P
-If you don\'t want to contribute patches, that\'s also cool\. It\'s very helpful to have people play with npm and send issues or complaints\. It\'s stable in what it does, so you may find it useful even if you just link in your stuff by doing \fBnpm link \.\fR to put it in the \fBNODE_PATH\fR so you can pull it in more easily\.
+When you find issues, please report them:
 .
-.P
-If you have strong feelings about package managers, I\'d love to hear your opinions\.
+.TP
+web
+\fIhttp://github\.com/isaacs/npm/issues\fR
 .
-.P
-You can usually find me in #node\.js on freenode\.net, or you can reach me via i@izs\.me\.
+.TP
+email
+\fInpm\-@googlegroups\.com\fR
 .
-.SH "Todo"
-See \fIhttp://github\.com/isaacs/npm/issues\fR for current todo list\.
+.P
+Be sure to include \fIall\fR of the output from the npm command that didn\'t work as expected\.
 .
-.SH "Version History"
+.SH "HISTORY"
 .
 .TP
 0\.0\.1
@@ -309,9 +295,4 @@ Fix a bunch of bugs
 .
 .br
 Some minor speed improvements
-.
-.SH "SEE ALSO"
-npm\-help(1)
-.
-.br
 
diff --git a/man/scripts.1 b/man/scripts.1
index 8c568a6fa..d65b09709 100644
--- a/man/scripts.1
+++ b/man/scripts.1
@@ -1,7 +1,7 @@
 .\" generated with Ronn/v0.7.3
 .\" http://github.com/rtomayko/ronn/tree/0.7.3
 .
-.TH "NPM\-SCRIPTS" "1" "May 2010" "" ""
+.TH "NPM\-SCRIPTS" "1" "July 2010" "" ""
 .
 .SH "NAME"
 \fBnpm\-scripts\fR \- How npm handles the "scripts" field
@@ -14,7 +14,7 @@ preinstall
 Run BEFORE the package is installed
 .
 .TP
-install
+install, postinstall
 Run AFTER the package is installed\.
 .
 .TP
@@ -22,11 +22,11 @@ preactivate
 Run BEFORE the package is activated\.
 .
 .TP
-activate
+activate, postactivate
 Run AFTER the package has been activated\.
 .
 .TP
-deactivate
+predeactivate, deactivate
 Run BEFORE the package is deactivated\.
 .
 .TP
@@ -34,7 +34,7 @@ postdeactivate
 Run AFTER the package is deactivated\.
 .
 .TP
-uninstall
+preuninstall, uninstall
 Run BEFORE the package is uninstalled\.
 .
 .TP
@@ -118,4 +118,4 @@ If you want to run a make command, you can do so\. This works just fine:
 .IP "" 0
 .
 .P
-However, the script line is not simply a command line, so \fBmake && make install\fR would try to execute the \fBmake\fR command with the arguments \fB&&\fR, \fBmake\fR, and \fBinstall\fR\. If you have a lot of stuff to run in a command, put it in a script file\.
+Scripts are run by passing the line as a script argument to \fBsh\fR\.