Wrapped README.md so that it displays properly on github

1 files changed, 148 insertions, 56 deletions

diff --git a/README.md b/README.md
index 1f54a3fd7..cc2fb9865 100644
--- a/README.md
+++ b/README.md
@@ -2,35 +2,55 @@
 
 npm is a little package manager for the Node javascript library.
 
-For now, this README is more of a task list/roadmap than a proper "how to use this" type doc.
+For now, this README is more of a task list/roadmap than a proper "how to use
+this" type doc.
 
 ## Status: alpha
 
-This thing is a baby yet.  But these kids grow up before you know it!  Pretty soon, you'll be all tapping out your pipe on the front porch, saying in your withered old man voice, <i>"I remember back before the war with the machines, when that npm thing couldn't even install itself, and didn't know what a version was.  We used promises for everything and the global object was called 'node'.  Movies were a nickel when we downloaded them from from the micro torrents, and soda pop had corn syrup of the highest fructose imaginable.  You youngins don't know how good you got it."</i>
+This thing is a baby yet. But these kids grow up before you know it! Pretty
+soon, you'll be all tapping out your pipe on the front porch, saying in your
+withered old man voice, <i>"I remember back before the war with the machines,
+when that npm thing couldn't even install itself, and didn't know what a
+version was. We used promises for everything and the global object was called
+'node'. Movies were a nickel when we downloaded them from from the micro
+torrents, and soda pop had corn syrup of the highest fructose imaginable. You
+youngins don't know how good you got it."</i>
 
-This isn't even beta, it's alpha.  When most of the core functionality is working, I'll make an announcement on the [node.js](http://groups.google.com/group/nodejs) list.  That'll be the `0.1.0` version.
+This isn't even beta, it's alpha. When most of the core functionality is
+working, I'll make an announcement on the
+[node.js](http://groups.google.com/group/nodejs) list. That'll be the `0.1.0`
+version.
 
 Here's what I mean by "core functionality":
 
 1. Install packages by name, and get the stable version.
-2. Install packages by supplying a name and version, and get the version specified.
-3. Install more than one package at a time by specifying them all on the command line.
-4. Install pre-requisites automatically, pulling the stable versions of the dependencies.
-5. Talk to a centralized repository to do all this package/version lookup magic.
-6. Install more than one version of a package, and optionally select an "active" version.
-7. Safely uninstall packages, not removing them unless they have no dependents.  (Override with a `--force` flag, of course.)
+2. Install packages by supplying a name and version, and get the version
+   specified.
+3. Install more than one package at a time by specifying them all on the
+   command line.
+4. Install pre-requisites automatically, pulling the stable versions of the
+   dependencies.
+5. Talk to a centralized repository to do all this package/version lookup
+   magic.
+6. Install more than one version of a package, and optionally select an
+   "active" version.
+7. Safely uninstall packages, not removing them unless they have no dependents.
+   (Override with a `--force` flag, of course.)
 8. Provide a utility for uploading a package.json to a js-registry repository.
 9. Handle circular dependencies nicely.
 10. Install and activate automatically.
 11. Read settings from a .npmrc file.
 12. Be much smarter about cli arguments.
 13. Help topics.
-14. Install a "link" to a dev directory, so that it links it in rather than doing the moveIntoPlace step.
-15. Detect when a package has only been installed as a dependency, and be able to remove it when nothing else depends on it.
+14. Install a "link" to a dev directory, so that it links it in rather than
+    doing the moveIntoPlace step.
+15. Detect when a package has only been installed as a dependency, and be able
+    to remove it when nothing else depends on it.
 
 ## Principles
 
-Put the files where they need to be so that node can find them using the methods it already uses.
+Put the files where they need to be so that node can find them using the
+methods it already uses.
 
 Be easy, not clever.
 
@@ -38,15 +58,21 @@ The file system is the database.
 
 Sync with the habits that are already in use.
 
-Packages should be maintained by their authors, not by the package manager author.  (Especially if that's me, because I'm lazy.)
+Packages should be maintained by their authors, not by the package manager
+author. (Especially if that's me, because I'm lazy.)
 
-Run it on node.  Cuz a node package manager should be written in evented javascript.
+Run it on node. Cuz a node package manager should be written in evented
+javascript.
 
 ## Contributing
 
-If you're interested in helping, that's awesome!  Please fork this project, implement some of the things on the list, and then let me know.  You can usually find me in #node.js on freenode.net, or you can reach me via <i@izs.me>.
+If you're interested in helping, that's awesome! Please fork this project,
+implement some of the things on the list, and then let me know. You can
+usually find me in #node.js on freenode.net, or you can reach me via
+<i@izs.me>.
 
-If you have strong feelings about package managers, I'd love to hear your opinions.
+If you have strong feelings about package managers, I'd love to hear your
+opinions.
 
 ## Installation
 
@@ -54,21 +80,27 @@ To install npm, do this:
 
     $ node install-npm.js
 
-That will use npm to install itself, like [Ouroboros](http://en.wikipedia.org/wiki/Ouroboros).  From there, you can call the command line program which is cleverly named `npm`.
+That will use npm to install itself, like
+[Ouroboros](http://en.wikipedia.org/wiki/Ouroboros). From there, you can call
+the command line program which is cleverly named `npm`.
 
 ## What works now:
 
-These are the commands that actually do things, as of today.  If they don't do what they say they do, then please post an issue about it.
+These are the commands that actually do things, as of today. If they don't do
+what they say they do, then please post an issue about it.
 
 ### install
 
     npm install <tarball>
 
-This installs the package, where `tarball` is a url or path to a `.tgz` file that contains a package with a `package.json` file in the root.
+This installs the package, where `tarball` is a url or path to a `.tgz` file
+that contains a package with a `package.json` file in the root.
 
-This'll create some stuff in `$HOME/.node_libraries`.  It supports installing multiple versions of the same thing.
+This'll create some stuff in `$HOME/.node_libraries`. It supports installing
+multiple versions of the same thing.
 
-From here, you can do `require("foo-1.2.3")` where "foo" is the name of the package, and "1.2.3" is the version you installed.
+From here, you can do `require("foo-1.2.3")` where "foo" is the name of the
+package, and "1.2.3" is the version you installed.
 
 Installing by name and version alone is planned for the next version.
 
@@ -76,37 +108,46 @@ Installing by name and version alone is planned for the next version.
 
     npm uninstall <name> <version>
 
-This uninstalls a package, completely removing everything installed for it.  If it's currently active, then it must be deactivated first.  If anything is depending on it, then those must be uninstalled first.
+This uninstalls a package, completely removing everything installed for it. If
+it's currently active, then it must be deactivated first. If anything is
+depending on it, then those must be uninstalled first.
 
 ### activate
 
     npm activate <name> <version>
 
-This "activates" a specific version of a package, so that you can just do `require("foo")` without having to specify the version.
+This "activates" a specific version of a package, so that you can just do
+`require("foo")` without having to specify the version.
 
 ### deactivate
 
     npm deactivate <name>
 
-If there's an active version of the package, this will unlink it from that preferential position.
+If there's an active version of the package, this will unlink it from that
+preferential position.
 
 ### link
 
     npm link <folder>
 
-This will link a source folder into npm's registry using a symlink, and then build it according to the package.json file in that folder's root.  This is handy for installing your own stuff, so that you can work on it and test it iteratively without having to continually rebuild.
+This will link a source folder into npm's registry using a symlink, and then
+build it according to the package.json file in that folder's root. This is
+handy for installing your own stuff, so that you can work on it and test it
+iteratively without having to continually rebuild.
 
 ### list
 
     npm list [package]
 
-This will show the installed (and, potentially, activated) versions of all the packages that npm has installed, or just the `package` if specified.
+This will show the installed (and, potentially, activated) versions of all the
+packages that npm has installed, or just the `package` if specified.
 
 This is also aliased to `ls`.
 
 ## Package Lifecycle Scripts
 
-npm supports the "scripts" member of the package.json script, for the following scripts:
+npm supports the "scripts" member of the package.json script, for the
+following scripts:
 
 `preinstall` - Run BEFORE the package is installed
 
@@ -126,24 +167,34 @@ npm supports the "scripts" member of the package.json script, for the following
 
 ### Package Lifecycle Env Vars
 
-Package scripts are run in an environment where the package.json fields have been tacked onto the `npm_package_` prefix.  So, for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your package.json file, then in your various lifecycle scripts, this would be true:
+Package scripts are run in an environment where the package.json fields have
+been tacked onto the `npm_package_` prefix. So, for instance, if you had
+`{"name":"foo", "version":"1.2.5"}` in your package.json file, then in your
+various lifecycle scripts, this would be true:
 
     process.env.npm_package_name === "foo"
     process.env.npm_package_version === "1.2.5"
 
-Objects are flattened following this format, so if you had `{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this in the script:
+Objects are flattened following this format, so if you had
+`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd see this
+in the script:
 
     process.env.npm_package_scripts_install = "foo.js"
 
-Last but not least, the `npm_lifecycle_event` environment variable is set to whichever stage of the cycle is being executed.  So, you could have a single script used for different parts of the process which switches based on what's currently happening.
+Last but not least, the `npm_lifecycle_event` environment variable is set to
+whichever stage of the cycle is being executed. So, you could have a single
+script used for different parts of the process which switches based on what's
+currently happening.
 
-If the script exits with a code other than 0, then this will abort the process.
+If the script exits with a code other than 0, then this will abort the
+process.
 
-Note that these script files don't have to be nodejs or even javascript programs.  They just have to be some kind of executable file.
+Note that these script files don't have to be nodejs or even javascript
+programs. They just have to be some kind of executable file.
 
 For example, if your package.json contains this:
 
-    { "scripts" : 
+    { "scripts" :
       { "install" : "scripts/install.js"
       , "postinstall" : "scripts/install.js"
       , "activate" : "scripts/install.js"
@@ -151,25 +202,39 @@ For example, if your package.json contains this:
       }
     }
 
-then the `scripts/install.js` will be called for the install, post-install, and activate stages of the lifecycle, and the `scripts/uninstall.js` would be called when the package is uninstalled.
+then the `scripts/install.js` will be called for the install, post-install,
+and activate stages of the lifecycle, and the `scripts/uninstall.js` would be
+called when the package is uninstalled.
 
 ## Deviations from and Extensions to the Packages/1.0 Spec
 
-npm aims to implement the commonjs [Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec.  However, some adjustments have been made, which may eventually be unmade, but hopefully will be incorporated into the spec.
+npm aims to implement the commonjs
+[Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec. However, some
+adjustments have been made, which may eventually be unmade, but hopefully will
+be incorporated into the spec.
 
 ### version
 
-Version must be [semver](http://semver.org)-compliant.  npm assumes that you've read the semver page, and that you comply with it.  Versions packages with non-semver versions will not be installed by npm.  It's just too tricky if you have more than one way to do it, and semver works well.
+Version must be [semver](http://semver.org)-compliant. npm assumes that you've
+read the semver page, and that you comply with it. Versions packages with
+non-semver versions will not be installed by npm. It's just too tricky if you
+have more than one way to do it, and semver works well.
 
-(This is actually mentioned in the Packages/1.0 spec, but it's worth mentioning that npm enforces this requirement quite strictly, since it's pretty liberal about most other things.)
+(This is actually mentioned in the Packages/1.0 spec, but it's worth
+mentioning that npm enforces this requirement quite strictly, since it's
+pretty liberal about most other things.)
 
 ### dependencies
 
-The Packages/1.0 spec's method for specifying dependencies is Unclean in My Sight.  So, npm is using a very simple semver-based method.
+The Packages/1.0 spec's method for specifying dependencies is Unclean in My
+Sight. So, npm is using a very simple semver-based method.
 
-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.
 
-Version range descriptors may be any of the following styles, where "version" is a semver compatible version identifier.
+Version range descriptors may be any of the following styles, where "version"
+is a semver compatible version identifier.
 
 1. `version` Must match `version` exactly
 2. `=version` Same as just `version`
@@ -183,7 +248,7 @@ Version range descriptors may be any of the following styles, where "version" is
 
 For example, these are all valid:
 
-    { "dependencies" : 
+    { "dependencies" :
       { "foo" : "1.0.0 - 2.9999.9999"
       , "bar" : ">=1.0.2 <2.1.2"
       , "baz" : ">1.0.2 <=2.3.4"
@@ -193,15 +258,16 @@ For example, these are all valid:
 
 ### link
 
-You may specify a `link` member in your package.json to have npm link dependencies in to a particular location inside your package dir.  For example:
+You may specify a `link` member in your package.json to have npm link
+dependencies in to a particular location inside your package dir. For example:
 
-    { "dependencies" : 
+    { "dependencies" :
       { "boo" : "2.0.1"
       , "baz" : ">1.0.2 <=2.3.4"
       , "foo" : "1.0.0 - 2.9999.9999"
       , "bar" : ">=1.0.2 <2.1.2"
       }
-    , "link" : 
+    , "link" :
       { "boo" : "./deps/boo"
       , "baz" : "./lib/baz"
       , "foo" : "./deps/foo"
@@ -209,15 +275,23 @@ You may specify a `link` member in your package.json to have npm link dependenci
       }
     }
 
-This would link the dependencies into the specified locations, so that the package code could do `require("./deps/foo")` to import whichever version of `foo` was satisfying the requirement.
+This would link the dependencies into the specified locations, so that the
+package code could do `require("./deps/foo")` to import whichever version of
+`foo` was satisfying the requirement.
 
-<strong style="color:red">Warning!</strong> This is currently the *only* way in which npm modifies the pristine nature of the package directory, and it may go away eventually.  It's just that it satisfies a use case that is pretty tricky to do otherwise.
+<strong style="color:red">Warning!</strong> This is currently the *only* way
+in which npm modifies the pristine nature of the package directory, and it may
+go away eventually. It's just that it satisfies a use case that is pretty
+tricky to do otherwise.
 
 ### engines
 
-Packages/1.0 says that you can have an "engines" field with an array of engine names.  However, it has no provision for specifying which version of the engine your stuff runs on.
+Packages/1.0 says that you can have an "engines" field with an array of engine
+names. However, it has no provision for specifying which version of the engine
+your stuff runs on.
 
-With npm, you can use either of the following styles to specify the version of node that your stuff works on:
+With npm, you can use either of the following styles to specify the version of
+node that your stuff works on:
 
     { "engines" : [ "node >=0.1.27 <0.1.30" ] }
 
@@ -225,21 +299,33 @@ or:
 
     { "engines" : { "node" : ">=0.1.27 <0.1.30" } }
 
-And, like with dependencies, if you don't specify the version (or if you specify "*" as the version), then any version of node will do.
+And, like with dependencies, if you don't specify the version (or if you
+specify "*" as the version), then any version of node will do.
 
-If you specify an "engines" field, then npm will require that "node" be somewhere on that list.  If "engines" is omitted, then npm will just assume that it works on node.
+If you specify an "engines" field, then npm will require that "node" be
+somewhere on that list. If "engines" is omitted, then npm will just assume
+that it works on node.
 
 ### bin
 
-A lot of packages have one or more executable files that they'd like to install into the PATH.  npm makes this pretty easy (in fact, it uses this feature to install the "npm" executable.)
+A lot of packages have one or more executable files that they'd like to
+install into the PATH. npm makes this pretty easy (in fact, it uses this
+feature to install the "npm" executable.)
 
-To use this, supply a `bin` field in your package.json which is a map of command name to local file name.  On install, npm will link that file into place right next to wherever node is installed.  (Presumably, this is in your PATH, and defaults to `/usr/local/bin`.)  On activation, the versioned file will get linked to the main filename (just like how the main.js stuff works, but with an executable in the PATH.)
+To use this, supply a `bin` field in your package.json which is a map of
+command name to local file name. On install, npm will link that file into
+place right next to wherever node is installed. (Presumably, this is in your
+PATH, and defaults to `/usr/local/bin`.) On activation, the versioned file
+will get linked to the main filename (just like how the main.js stuff works,
+but with an executable in the PATH.)
 
 For example, npm has this:
 
     { "bin" : { "npm" : "./cli.js" } }
 
-So, when you install npm, it'll create a symlink from the `cli.js` script to `/usr/local/bin/npm-version`.  Then, when you activate that version, it'll create a symlink from `/usr/local/bin/npm-version` to `/usr/local/bin/npm`.
+So, when you install npm, it'll create a symlink from the `cli.js` script to
+`/usr/local/bin/npm-version`. Then, when you activate that version, it'll
+create a symlink from `/usr/local/bin/npm-version` to `/usr/local/bin/npm`.
 
 (props to [mikeal](http://github.com/mikeal) for the idea)
 
@@ -248,7 +334,10 @@ So, when you install npm, it'll create a symlink from the `cli.js` script to `/u
 All the "core functionality" stuff above.  Most immediately:
 
 * Install packages from the registry.
-* Install missing dependencies.  For each one, fetch it, then figure out what it needs, then fetch that if we don't already have it, etc.  Put off the resolveDependencies step until everything on the list has been installed, then go back and do the dependency linking.
+* Install missing dependencies. For each one, fetch it, then figure out what
+  it needs, then fetch that if we don't already have it, etc. Put off the
+  resolveDependencies step until everything on the list has been installed,
+  then go back and do the dependency linking.
 * Uninstall dependent packages.
 * Update dependencies when a new satisfying version is installed.
 * Make the CLI not so user-hostile.
@@ -257,7 +346,9 @@ Some "nice to have" things that aren't quite core:
 
 * Use path.relative so that the whole root can be picked up and moved easily.
 * Specify the root (and other global options, perhaps) to the CLI.
-* Parse command line options better, and pass an object to the npm command functions, rather than having everything just take one or two positional arguments.
+* Parse command line options better, and pass an object to the npm command
+  functions, rather than having everything just take one or two positional
+  arguments.
 
 ## Version History
 
@@ -286,4 +377,5 @@ Some "nice to have" things that aren't quite core:
 ### 0.0.5
 
 * fix a few bugs in uninstall wrt dependent packages
-* fix relative require() for nodejs modules installed with the "bin" field. (issue #2)
+* fix relative require()for nodejs modules installed with the "bin" field.
+  (issue #2)