npm-install.roff.patch

--- test.1	2014-09-21 00:50:56.000000000 -0700
+++ test.3	2014-09-21 00:57:02.000000000 -0700
@@ -1,10 +1,14 @@
+.\" Generated with Ronnjs 0.4.0
+.\" http://github.com/kapouer/ronnjs
+.
 .TH "NPM\-INSTALL" "1" "September 2014" "" ""
+.
 .SH "NAME"
-\fBnpm-install\fR \- Install a package
-.SH SYNOPSIS
-.P
-.RS 2
-.EX
+\fBnpm-install\fR \-\- Install a package
+.
+.SH "SYNOPSIS"
+.
+.nf
 npm install (with no args in a package dir)
 npm install <tarball file>
 npm install <tarball url>
@@ -14,257 +18,382 @@
 npm install [@<scope>/]<name>@<version>
 npm install [@<scope>/]<name>@<version range>
 npm i (with any of the previous argument usage)
-.EE
-.RE
-.SH DESCRIPTION
-.P
+.
+.fi
+.
+.SH "DESCRIPTION"
 This command installs a package, and any packages that it depends on\. If the
 package has a shrinkwrap file, the installation of dependencies will be driven
 by that\. See npm\-shrinkwrap(1)\.
+.
 .P
 A \fBpackage\fR is:
-.RS 0
-.IP \(bu 2
+.
+.IP "\(bu" 4
 a) a folder containing a program described by a package\.json file
-.IP \(bu 2
+.
+.IP "\(bu" 4
 b) a gzipped tarball containing (a)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 c) a url that resolves to (b)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 d) a \fB<name>@<version>\fR that is published on the registry (see \fBnpm\-registry(7)\fR) with (c)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 e) a \fB<name>@<tag>\fR that points to (d)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 f) a \fB<name>\fR that has a "latest" tag satisfying (e)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 g) a \fB<git remote url>\fR that resolves to (b)
-
-.RE
+.
+.IP "" 0
+.
 .P
 Even if you never publish your package, you can still get a lot of
 benefits of using npm if you just want to write a node program (a), and
 perhaps if you also want to be able to easily install it elsewhere
 after packing it up into a tarball (b)\.
-.RS 0
-.IP \(bu 2
+.
+.IP "\(bu" 4
 \fBnpm install\fR (in package directory, no arguments):
-  Install the dependencies in the local node_modules folder\.
-  In global mode (ie, with \fB\-g\fR or \fB\-\-global\fR appended to the command),
-  it installs the current package context (ie, the current working
-  directory) as a global package\.
-  By default, \fBnpm install\fR will install all modules listed as
-  dependencies\. With the \fB\-\-production\fR flag,
-  npm will not install modules listed in \fBdevDependencies\fR\|\.
-.IP \(bu 2
+.
+.IP
+Install the dependencies in the local node_modules folder\.
+.
+.IP
+In global mode (ie, with \fB\-g\fR or \fB\-\-global\fR appended to the command),
+it installs the current package context (ie, the current working
+directory) as a global package\.
+.
+.IP
+By default, \fBnpm install\fR will install all modules listed as
+dependencies\. With the \fB\-\-production\fR flag,
+npm will not install modules listed in \fBdevDependencies\fR\|\.
+.
+.IP "\(bu" 4
 \fBnpm install <folder>\fR:
-  Install a package that is sitting in a folder on the filesystem\.
-.IP \(bu 2
+.
+.IP
+Install a package that is sitting in a folder on the filesystem\.
+.
+.IP "\(bu" 4
 \fBnpm install <tarball file>\fR:
-  Install a package that is sitting on the filesystem\.  Note: if you just want
-  to link a dev directory into your npm root, you can do this more easily by
-  using \fBnpm link\fR\|\.
-  Example:
-.P
-.RS 2
-.EX
-    npm install \./package\.tgz
-.EE
-.RE
-.IP \(bu 2
+.
+.IP
+Install a package that is sitting on the filesystem\.  Note: if you just want
+to link a dev directory into your npm root, you can do this more easily by
+using \fBnpm link\fR\|\.
+.
+.IP
+Example:
+.
+.IP "" 4
+.
+.nf
+  npm install \./package\.tgz
+.
+.fi
+.
+.IP "" 0
+
+.
+.IP "\(bu" 4
 \fBnpm install <tarball url>\fR:
-  Fetch the tarball url, and then install it\.  In order to distinguish between
-  this and other options, the argument must start with "http://" or "https://"
-  Example:
-.P
-.RS 2
-.EX
-    npm install https://github\.com/indexzero/forever/tarball/v0\.5\.6
-.EE
-.RE
-.IP \(bu 2
+.
+.IP
+Fetch the tarball url, and then install it\.  In order to distinguish between
+this and other options, the argument must start with "http://" or "https://"
+.
+.IP
+Example:
+.
+.IP "" 4
+.
+.nf
+  npm install https://github\.com/indexzero/forever/tarball/v0\.5\.6
+.
+.fi
+.
+.IP "" 0
+
+.
+.IP "\(bu" 4
 \fBnpm install [@<scope>/]<name> [\-\-save|\-\-save\-dev|\-\-save\-optional]\fR:
-  Do a \fB<name>@<tag>\fR install, where \fB<tag>\fR is the "tag" config\. (See
-  \fBnpm\-config(7)\fR\|\.)
-  In most cases, this will install the latest version
-  of the module published on npm\.
-  Example:
-.P
-.RS 2
-.EX
-    npm install sax
-.EE
-.RE
-  \fBnpm install\fR takes 3 exclusive, optional flags which save or update
-  the package version in your main package\.json:
-.RS 0
-.IP \(bu 2
+.
+.IP
+Do a \fB<name>@<tag>\fR install, where \fB<tag>\fR is the "tag" config\. (See \fBnpm\-config(7)\fR\|\.)
+.
+.IP
+In most cases, this will install the latest version
+of the module published on npm\.
+.
+.IP
+Example:
+.
+.IP "" 4
+.
+.nf
+  npm install sax
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+\fBnpm install\fR takes 3 exclusive, optional flags which save or update
+the package version in your main package\.json:
+.
+.IP "\(bu" 4
 \fB\-\-save\fR: Package will appear in your \fBdependencies\fR\|\.
-.IP \(bu 2
+.
+.IP "\(bu" 4
 \fB\-\-save\-dev\fR: Package will appear in your \fBdevDependencies\fR\|\.
-.IP \(bu 2
+.
+.IP "\(bu" 4
 \fB\-\-save\-optional\fR: Package will appear in your \fBoptionalDependencies\fR\|\.
+.
+.IP "" 0
+.
+.IP
 When using any of the above options to save dependencies to your
 package\.json, there is an additional, optional flag:
-.IP \(bu 2
+.
+.IP "\(bu" 4
 \fB\-\-save\-exact\fR: Saved dependencies will be configured with an
-exact version rather than using npm's default semver range
+exact version rather than using npm\'s default semver range
 operator\.
+.
+.IP "" 0
+.
+.IP
 \fB<scope>\fR is optional\. The package will be downloaded from the registry
 associated with the specified scope\. If no registry is associated with
 the given scope the default registry is assumed\. See \fBnpm\-scope(7)\fR\|\.
+.
+.IP
 Note: if you do not include the @\-symbol on your scope name, npm will
 interpret this as a GitHub repository instead, see below\. Scopes names
 must also be followed by a slash\.
+.
+.IP
 Examples:
-.P
-.RS 2
-.EX
-npm install sax \-\-save
-npm install githubname/reponame
-npm install @myorg/privatepackage
-npm install node\-tap \-\-save\-dev
-npm install dtrace\-provider \-\-save\-optional
-npm install readable\-stream \-\-save \-\-save\-exact
-.EE
-.RE
-
-.RE
-
-.RE
-.P
-.RS 2
-.EX
-**Note**: If there is a file or folder named `<name>` in the current
+.
+.IP "" 4
+.
+.nf
+  npm install sax \-\-save
+  npm install githubname/reponame
+  npm install @myorg/privatepackage
+  npm install node\-tap \-\-save\-dev
+  npm install dtrace\-provider \-\-save\-optional
+  npm install readable\-stream \-\-save \-\-save\-exact
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+\fBNote\fR: If there is a file or folder named \fB<name>\fR in the current
 working directory, then it will try to install that, and only try to
 fetch the package by name if it is not valid\.
-.EE
-.RE
-.RS 0
-.IP \(bu 2
+.
+.IP "\(bu" 4
 \fBnpm install [@<scope>/]<name>@<tag>\fR:
-  Install the version of the package that is referenced by the specified tag\.
-  If the tag does not exist in the registry data for that package, then this
-  will fail\.
-  Example:
-.P
-.RS 2
-.EX
-    npm install sax@latest
-    npm install @myorg/mypackage@latest
-.EE
-.RE
-.IP \(bu 2
+.
+.IP
+Install the version of the package that is referenced by the specified tag\.
+If the tag does not exist in the registry data for that package, then this
+will fail\.
+.
+.IP
+Example:
+.
+.IP "" 4
+.
+.nf
+  npm install sax@latest
+  npm install @myorg/mypackage@latest
+.
+.fi
+.
+.IP "" 0
+
+.
+.IP "\(bu" 4
 \fBnpm install [@<scope>/]<name>@<version>\fR:
-  Install the specified version of the package\.  This will fail if the
-  version has not been published to the registry\.
-  Example:
-.P
-.RS 2
-.EX
-    npm install sax@0\.1\.1
-    npm install @myorg/privatepackage@1\.5\.0
-.EE
-.RE
-.IP \(bu 2
+.
+.IP
+Install the specified version of the package\.  This will fail if the
+version has not been published to the registry\.
+.
+.IP
+Example:
+.
+.IP "" 4
+.
+.nf
+  npm install sax@0\.1\.1
+  npm install @myorg/privatepackage@1\.5\.0
+.
+.fi
+.
+.IP "" 0
+
+.
+.IP "\(bu" 4
 \fBnpm install [@<scope>/]<name>@<version range>\fR:
-  Install a version of the package matching the specified version range\.  This
-  will follow the same rules for resolving dependencies described in \fBpackage\.json(5)\fR\|\.
-  Note that most version ranges must be put in quotes so that your shell will
-  treat it as a single argument\.
-  Example:
-.P
-.RS 2
-.EX
-    npm install sax@">=0\.1\.0 <0\.2\.0"
-    npm install @myorg/privatepackage@">=0\.1\.0 <0\.2\.0"
-.EE
-.RE
-.IP \(bu 2
+.
+.IP
+Install a version of the package matching the specified version range\.  This
+will follow the same rules for resolving dependencies described in \fBpackage\.json(5)\fR\|\.
+.
+.IP
+Note that most version ranges must be put in quotes so that your shell will
+treat it as a single argument\.
+.
+.IP
+Example:
+.
+.IP "" 4
+.
+.nf
+  npm install sax@">=0\.1\.0 <0\.2\.0"
+  npm install @myorg/privatepackage@">=0\.1\.0 <0\.2\.0"
+.
+.fi
+.
+.IP "" 0
+
+.
+.IP "\(bu" 4
 \fBnpm install <githubname>/<githubrepo>\fR:
-  Install the package at \fBhttps://github\.com/githubname/githubrepo" by
-  attempting to clone it using\fRgit`\.
-  Example:
-.P
-.RS 2
-.EX
-    npm install mygithubuser/myproject
-.EE
-.RE
- To reference a package in a git repo that is not on GitHub, see git
- remote urls below\.
-.IP \(bu 2
+.
+.IP
+Install the package at \fBhttps://github\.com/githubname/githubrepo" by
+attempting to clone it using \fRgit`\.
+.
+.IP
+Example:
+.
+.IP "" 4
+.
+.nf
+  npm install mygithubuser/myproject
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+To reference a package in a git repo that is not on GitHub, see git
+remote urls below\.
+.
+.IP "\(bu" 4
 \fBnpm install <git remote url>\fR:
-  Install a package by cloning a git remote url\.  The format of the git
-  url is:
-.P
-.RS 2
-.EX
-    <protocol>://[<user>@]<hostname><separator><path>[#<commit\-ish>]
-.EE
-.RE
-  \fB<protocol>\fR is one of \fBgit\fR, \fBgit+ssh\fR, \fBgit+http\fR, or
-  \fBgit+https\fR\|\.  If no \fB<commit\-ish>\fR is specified, then \fBmaster\fR is
-  used\.
-  Examples:
-.P
-.RS 2
-.EX
-    git+ssh://git@github\.com:npm/npm\.git#v1\.0\.27
-    git+https://isaacs@github\.com/npm/npm\.git
-    git://github\.com/npm/npm\.git#v1\.0\.27
-.EE
-.RE
+.
+.IP
+Install a package by cloning a git remote url\.  The format of the git
+url is:
+.
+.IP "" 4
+.
+.nf
+  <protocol>://[<user>@]<hostname><separator><path>[#<commit\-ish>]
+.
+.fi
+.
+.IP "" 0
+.
+.IP
+\fB<protocol>\fR is one of \fBgit\fR, \fBgit+ssh\fR, \fBgit+http\fR, or \fBgit+https\fR\|\.  If no \fB<commit\-ish>\fR is specified, then \fBmaster\fR is
+used\.
+.
+.IP
+Examples:
+.
+.IP "" 4
+.
+.nf
+  git+ssh://git@github\.com:npm/npm\.git#v1\.0\.27
+  git+https://isaacs@github\.com/npm/npm\.git
+  git://github\.com/npm/npm\.git#v1\.0\.27
+.
+.fi
+.
+.IP "" 0
 
-.RE
+.
+.IP "" 0
+.
 .P
 You may combine multiple arguments, and even multiple types of arguments\.
 For example:
-.P
-.RS 2
-.EX
+.
+.IP "" 4
+.
+.nf
 npm install sax@">=0\.1\.0 <0\.2\.0" bench supervisor
-.EE
-.RE
+.
+.fi
+.
+.IP "" 0
+.
 .P
 The \fB\-\-tag\fR argument will apply to all of the specified install targets\. If a
 tag with the given name exists, the tagged version is preferred over newer
 versions\.
+.
 .P
 The \fB\-\-force\fR argument will force npm to fetch remote resources even if a
 local copy exists on disk\.
-.P
-.RS 2
-.EX
+.
+.IP "" 4
+.
+.nf
 npm install sax \-\-force
-.EE
-.RE
+.
+.fi
+.
+.IP "" 0
+.
 .P
 The \fB\-\-global\fR argument will cause npm to install the package globally
 rather than locally\.  See \fBnpm\-folders(5)\fR\|\.
+.
 .P
 The \fB\-\-link\fR argument will cause npm to link global installs into the
 local space in some cases\.
+.
 .P
 The \fB\-\-no\-bin\-links\fR argument will prevent npm from creating symlinks for
 any binaries the package might contain\.
+.
 .P
 The \fB\-\-no\-optional\fR argument will prevent optional dependencies from
 being installed\.
+.
 .P
 The \fB\-\-no\-shrinkwrap\fR argument, which will ignore an available
 shrinkwrap file and use the package\.json instead\.
+.
 .P
 The \fB\-\-nodedir=/path/to/node/source\fR argument will allow npm to find the
 node source code so that npm can compile native modules\.
+.
 .P
 See \fBnpm\-config(7)\fR\|\.  Many of the configuration params have some
-effect on installation, since that's most of what npm does\.
-.SH ALGORITHM
-.P
+effect on installation, since that\'s most of what npm does\.
+.
+.SH "ALGORITHM"
 To install a package, npm uses the following algorithm:
-.P
-.RS 2
-.EX
+.
+.IP "" 4
+.
+.nf
 install(where, what, family, ancestors)
 fetch what, unpack to <where>/node_modules/<what>
 for each dep in what\.dependencies
@@ -274,78 +403,103 @@
     and not in <family>
   add precise version deps to <family>
   install(<where>/node_modules/<what>, dep, family)
-.EE
-.RE
+.
+.fi
+.
+.IP "" 0
+.
 .P
 For this \fBpackage{dep}\fR structure: \fBA{B,C}, B{C}, C{D}\fR,
 this algorithm produces:
-.P
-.RS 2
-.EX
+.
+.IP "" 4
+.
+.nf
 A
 +\-\- B
 `\-\- C
     `\-\- D
-.EE
-.RE
+.
+.fi
+.
+.IP "" 0
+.
 .P
 That is, the dependency from B to C is satisfied by the fact that A
 already caused C to be installed at a higher level\.
+.
 .P
 See npm\-folders(5) for a more detailed description of the specific
 folder structures that npm creates\.
-.SS Limitations of npm's Install Algorithm
-.P
+.
+.SS "Limitations of npm&#39;s Install Algorithm"
 There are some very rare and pathological edge\-cases where a cycle can
 cause npm to try to install a never\-ending tree of packages\.  Here is
 the simplest case:
+.
+.IP "" 4
+.
+.nf
+A \-> B \-> A\' \-> B\' \-> A \-> B \-> A\' \-> B\' \-> A \-> \.\.\.
+.
+.fi
+.
+.IP "" 0
+.
 .P
-.RS 2
-.EX
-A \-> B \-> A' \-> B' \-> A \-> B \-> A' \-> B' \-> A \-> \.\.\.
-.EE
-.RE
-.P
-where \fBA\fR is some version of a package, and \fBA'\fR is a different version
+where \fBA\fR is some version of a package, and \fBA\'\fR is a different version
 of the same package\.  Because \fBB\fR depends on a different version of \fBA\fR
 than the one that is already in the tree, it must install a separate
-copy\.  The same is true of \fBA'\fR, which must install \fBB'\fR\|\.  Because \fBB'\fR
+copy\.  The same is true of \fBA\'\fR, which must install \fBB\'\fR\|\.  Because \fBB\'\fR
 depends on the original version of \fBA\fR, which has been overridden, the
 cycle falls into infinite regress\.
+.
 .P
-To avoid this situation, npm flat\-out refuses to install any
-\fBname@version\fR that is already present anywhere in the tree of package
+To avoid this situation, npm flat\-out refuses to install any \fBname@version\fR that is already present anywhere in the tree of package
 folder ancestors\.  A more correct, but more complex, solution would be
 to symlink the existing version into the new location\.  If this ever
 affects a real use\-case, it will be investigated\.
-.SH SEE ALSO
-.RS 0
-.IP \(bu 2
+.
+.SH "SEE ALSO"
+.
+.IP "\(bu" 4
 npm\-folders(5)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-update(1)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-link(1)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-rebuild(1)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-scripts(7)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-build(1)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-config(1)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-config(7)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npmrc(5)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-registry(7)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-tag(1)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-rm(1)
-.IP \(bu 2
+.
+.IP "\(bu" 4
 npm\-shrinkwrap(1)
-
-.RE
+.
+.IP "" 0