Docs for new npm view command

1 files changed, 69 insertions, 5 deletions

diff --git a/doc/view.md b/doc/view.md
index 41a1fa835..e89816a1d 100644
--- a/doc/view.md
+++ b/doc/view.md
@@ -3,12 +3,76 @@ npm-view(1) -- View registry info
 
 ## SYNOPSIS
 
-    npm view [<pkg> [<pkg> ...]]
+    npm view pkg[@version] [<field>[.subfield]...]
 
 ## DESCRIPTION
 
-This command just spits out the data that is on the npm registry for a given
-package or packages.
+This command shows data about a package and prints it to the stream
+referenced by the `outfd` config, which defaults to stdout.
 
-You could also go to the registry url directly in your web browser to see the
-same information.
+To show the package registry entry for the `connect` package, you can do
+this:
+
+    npm view connect
+
+The default version is "latest" if unspecified.
+
+Field names can be specified after the package descriptor.
+For example, to show the dependencies of the `ronn` package at version
+0.3.5, you could do the following:
+
+    npm view ronn@0.3.5 dependencies
+
+You can view child field by separating them with a period.
+To view the git repository URL for the latest version of npm, you could
+do this:
+
+    npm view npm repository.url
+
+This makes it easy to view information about a dependency with a bit of
+shell scripting.  For example, to view all the data about the version of
+opts that ronn depends on, you can do this:
+
+    npm view opts@$(npm view ronn dependencies.opts)
+
+For fields that are arrays, requesting a non-numeric field will return
+all of the values from the objects in the list.  For example, to get all
+the contributor names for the "express" project, you can do this:
+
+    npm view express contributors.email
+
+You may also use numeric indices in square braces to specifically select
+an item in an array field.  To just get the email address of the first
+contributor in the list, you can do this:
+
+    npm view express contributors[0].email
+
+Multiple fields may be specified, and will be printed one after another.
+For exampls, to get all the contributor names and email addresses, you
+can do this:
+
+    npm view express contributors.name contributors.email
+
+"Person" fields are shown as a string if they would be shown as an
+object.  So, for example, this will show the list of npm contributors in
+the shortened string format.  (See `npm help json` for more on this.)
+
+    npm view npm contributors
+
+If a version range is provided, then data will be printed for every
+matching version of the package.  This will show which version of jsdom
+was required by each matching version of yui3:
+
+    npm view yui3@'>0.5.4' dependencies.jsdom
+
+## OUTPUT
+
+If only a single string field for a single version is output, then it
+will not be colorized or quoted, so as to enable piping the output to
+another command.
+
+If the version range matches multiple versions, than each printed value
+will be prefixed with the version it applies to.
+
+If multiple fields are requested, than each of them are prefixed with
+the field name.