Permalink
Browse files

make doc

  • Loading branch information...
1 parent 9eddacd commit 4ad295c09834965b7e6e0fcf45d8d7e4fe6ad98d @isaacs isaacs committed Jul 23, 2010
Showing with 109 additions and 69 deletions.
  1. +5 −10 man/config.1
  2. +3 −12 man/folders.1
  3. +76 −3 man/help.1
  4. +2 −2 man/json.1
  5. +17 −36 man/npm.1
  6. +6 −6 man/scripts.1
View
@@ -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
View
@@ -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
View
@@ -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\.
View
@@ -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\.
View
@@ -18,34 +18,18 @@ 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\.
.
.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
View
@@ -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,27 +14,27 @@ preinstall
Run BEFORE the package is installed
.
.TP
-install
+install, postinstall
Run AFTER the package is installed\.
.
.TP
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
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\.

0 comments on commit 4ad295c

Please sign in to comment.