make doc

5 files changed, 211 insertions, 11 deletions

diff --git a/man1/config.1 b/man1/config.1
index 260b9a2fc..e76bbc246 100644
--- a/man1/config.1
+++ b/man1/config.1
@@ -107,6 +107,47 @@ npm config edit
 .P
 Opens the config file in an editor\.  Use the \fB\-\-global\fR flag to edit the global config\.
 .
+.SH "Per\-Package Config Settings"
+When running scripts (see \fBnpm help scripts\fR)
+the package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\.  For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
 .SH "Config Settings"
 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 
diff --git a/man1/get.1 b/man1/get.1
index 260b9a2fc..e76bbc246 100644
--- a/man1/get.1
+++ b/man1/get.1
@@ -107,6 +107,47 @@ npm config edit
 .P
 Opens the config file in an editor\.  Use the \fB\-\-global\fR flag to edit the global config\.
 .
+.SH "Per\-Package Config Settings"
+When running scripts (see \fBnpm help scripts\fR)
+the package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\.  For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
 .SH "Config Settings"
 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 
diff --git a/man1/json.1 b/man1/json.1
index ab0f50167..2142c2b57 100644
--- a/man1/json.1
+++ b/man1/json.1
@@ -1,7 +1,7 @@
 .\" Generated with Ronnjs/v0.1
 .\" http://github.com/kapouer/ronnjs/
 .
-.TH "NPM\-JSON" "1" "December 2010" "" ""
+.TH "NPM\-JSON" "1" "January 2011" "" ""
 .
 .SH "NAME"
 \fBnpm-json\fR \-\- Specifics of npm\'s package\.json handling
@@ -124,6 +124,23 @@ Both email and url are optional either way\.
 .P
 npm also sets a top\-level "maintainers" field with your npm user info\.
 .
+.SH "files"
+The "files" field is an array of files to include in your project\.  If
+you name a folder in the array, then it will also include the files
+inside that folder\.  The default is just \fB[""]\fR which includes the
+entire package folder in the tarball, but you may want to only include
+specific things\.
+.
+.P
+If you specify modules, bins, or man pages, then those will be
+automatically added to the files array, even if they would not
+ordinarily be included\.
+.
+.P
+You can also provide a "\.npmignore" file in the root of your package,
+which will keep files from being included, even if they would be picked
+up by the files array\.
+.
 .SH "main"
 The main field is a module ID that is the primary entry point to your program\.
 That is, if your package is named \fBfoo\fR, and a user installs it, and then does \fBrequire("foo")\fR, then your main module\'s exports object will be returned\.
@@ -384,6 +401,29 @@ event, and the value is the command to run at that point\.
 .P
 See \fBnpm help scripts\fR to find out more about writing package scripts\.
 .
+.SH "config"
+A "config" hash can be used to set configuration
+parameters used in package scripts that persist across upgrades\.  For
+instance, if a package had the following:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and then had a "start" command that then referenced the \fBnpm_package_config_port\fR environment variable, then the user could
+override that by doing \fBnpm config set foo:port 8001\fR\|\.
+.
+.P
+See \fBnpm help config\fR and \fBnpm help scripts\fR for more on package
+configs\.
+.
 .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
diff --git a/man1/scripts.1 b/man1/scripts.1
index 39f2aee39..bf2dd76f6 100644
--- a/man1/scripts.1
+++ b/man1/scripts.1
@@ -1,7 +1,7 @@
 .\" Generated with Ronnjs/v0.1
 .\" http://github.com/kapouer/ronnjs/
 .
-.TH "NPM\-SCRIPTS" "1" "December 2010" "" ""
+.TH "NPM\-SCRIPTS" "1" "January 2011" "" ""
 .
 .SH "NAME"
 \fBnpm-scripts\fR \-\- How npm handles the "scripts" field
@@ -81,29 +81,66 @@ stop and start scripts if no \fBrestart\fR script is provided\.
 Additionally, arbitrary scrips can be run by doing \fBnpm run\-script <stage> <pkg>\fR\|\.
 .
 .SH "ENVIRONMENT"
-Package scripts run in an environment where many pieces of information are made available regarding the setup of npm and the current state of the process\.
+Package scripts run in an environment where many pieces of information are
+made available regarding the setup of npm and the current state of the
+process\.
 .
-.IP "\(bu" 4
-package\.json vars:
+.SS "package\.json vars"
 The package\.json fields are tacked onto the \fBnpm_package_\fR prefix\. So, for
 instance, if you had \fB{"name":"foo", "version":"1\.2\.5"}\fR in your package\.json
 file, then your package scripts would have the \fBnpm_package_name\fR environment
 variable set to "foo", and the \fBnpm_package_version\fR set to "1\.2\.5"
 .
-.IP "\(bu" 4
-configuration vars:
+.SS "configuration"
 Configuration parameters are put in the environment with the \fBnpm_config_\fR
 prefix\. For instance, you can view the effective \fBroot\fR config by checking the \fBnpm_config_root\fR environment variable\.
 .
-.IP "\(bu" 4
-current lifecycle event:
+.SS "Special: package\.json "config" hash"
+The package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\.  For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
+.SS "current lifecycle event"
 Lastly, the \fBnpm_lifecycle_event\fR 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\.
 .
-.IP "" 0
-.
 .P
 Objects are flattened following this format, so if you had \fB{"scripts":{"install":"foo\.js"}}\fR in your package\.json, then you\'d see this
 in the script:
diff --git a/man1/set.1 b/man1/set.1
index 260b9a2fc..e76bbc246 100644
--- a/man1/set.1
+++ b/man1/set.1
@@ -107,6 +107,47 @@ npm config edit
 .P
 Opens the config file in an editor\.  Use the \fB\-\-global\fR flag to edit the global config\.
 .
+.SH "Per\-Package Config Settings"
+When running scripts (see \fBnpm help scripts\fR)
+the package\.json "config" keys are overwritten in the environment if
+there is a config param of \fB<name>[@<version>]:<key>\fR\|\.  For example, if
+the package\.json has this:
+.
+.IP "" 4
+.
+.nf
+{ "name" : "foo"
+, "config" : { "port" : "8080" }
+, "scripts" : { "start" : "node server\.js" } }
+.
+.fi
+.
+.IP "" 0
+.
+.P
+and the server\.js is this:
+.
+.IP "" 4
+.
+.nf
+http\.createServer(\.\.\.)\.listen(process\.env\.npm_package_config_port)
+.
+.fi
+.
+.IP "" 0
+.
+.P
+then the user could change the behavior by doing:
+.
+.IP "" 4
+.
+.nf
+npm config set foo:port 80
+.
+.fi
+.
+.IP "" 0
+.
 .SH "Config Settings"
 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