Clean up the docs further. Make them more consistent.

15 files changed, 66 insertions, 51 deletions

diff --git a/doc/activate.md b/doc/activate.md
index b71c6bb2c..25b6e6919 100644
--- a/doc/activate.md
+++ b/doc/activate.md
@@ -1,8 +1,12 @@
 npm activate(1) -- Activate an installed version of a package
 =============================================================
 
+## SYNOPSIS
+
     npm activate <name> <version>
 
+## DESCRIPTION
+
 This "activates" a specific version of a package, so that you can just do
 `require("foo")` without having to specify the version.
 
diff --git a/doc/adduser.md b/doc/adduser.md
index c969d77b4..55a82f7a6 100644
--- a/doc/adduser.md
+++ b/doc/adduser.md
@@ -1,8 +1,12 @@
 npm adduser(1) -- Add a registry user account
 =============================================
 
+## SYNOPSIS
+
     npm adduser bob password bob@email.com
 
+## DESCRIPTION
+
 Create a user named "bob" in the npm registry, and save the credentials to the
 `.npmrc` file. Note that this leaves the password in your `.bash_history`, and
 it is currently stored in the clear in the config file. So, don't use a
diff --git a/doc/cli.md b/doc/cli.md
deleted file mode 100644
index f7df3debc..000000000
--- a/doc/cli.md
+++ /dev/null
@@ -1,14 +0,0 @@
-# npm cli todos
-
-Update each function so that it takes an object bag of arguments. Update the
-cli.js to parse the user's .npmrc first, and then the arguments, merge the two
-objects together, and pass the data over to the function.
-
-If something relevant is missing, then each command should provide a "help"
-menu that lists out what's important for that command. Doing `npm help foo`
-should also output the "foo" command documentation.
-
-There needs to be a consistent pattern by which flags and other data is
-defined and named.
-
-Handle abbrevs.  Cuz that's just the nice thing to do.
diff --git a/doc/config.md b/doc/config.md
index 0ee9319a7..35aae9d00 100644
--- a/doc/config.md
+++ b/doc/config.md
@@ -1,6 +1,15 @@
 npm-config(1) -- Manage the npm configuration file
 ==================================================
 
+## SYNOPSIS
+
+    npm config set <key> <value>
+    npm config get <key>
+    npm config delete <key>
+    npm config list
+
+## DESCRIPTION
+
 The config command is a way to interact with the `.npmrc` file. This file is a
 JSON encoded list of values that npm is concerned with. The first time you run
 npm, it will create a conf file filled with default values.
@@ -36,7 +45,7 @@ Show all the config settings.
 **FIXME**: Prints to stderr, but should really be stdout, since the log is what
 you're after.
 
-### delete key
+### delete
 
     npm config delete key
 
diff --git a/doc/deactivate.md b/doc/deactivate.md
index 0eb69fa09..3a2136497 100644
--- a/doc/deactivate.md
+++ b/doc/deactivate.md
@@ -1,8 +1,12 @@
 npm-deactivate(1) -- Deactivate the active version of a package
 ===============================================================
 
+## SYNOPSIS
+
     npm deactivate <name>
 
+## DESCRIPTION
+
 If there's an active version of the package, this will unlink it from that
 preferential position.
 
diff --git a/doc/folders.md b/doc/folders.md
index 13de4bdcc..d2926c432 100644
--- a/doc/folders.md
+++ b/doc/folders.md
@@ -1,4 +1,7 @@
-# Folder Structures Used by npm
+npm-folders(1) -- Folder Structures Used by npm
+===============================================
+
+## DESCRIPTION
 
 Everything lives in the `root` setting. This defaults to
 `$HOME/.node_libraries/`. I'd like to be able to override it, but that's not
diff --git a/doc/help.md b/doc/help.md
index 41940a6dc..dfc19dce8 100644
--- a/doc/help.md
+++ b/doc/help.md
@@ -1,7 +1,7 @@
 npm-help(1) -- Get help about npm commands
 ==========================================
 
-## Usage
+## SYNOPSIS
 
     npm help <section>
 
diff --git a/doc/install.md b/doc/install.md
index c6f9d99c2..68ddb0dbf 100644
--- a/doc/install.md
+++ b/doc/install.md
@@ -1,7 +1,7 @@
 npm-install(1) -- install a package
 ===================================
 
-## SUMMARY
+## SYNOPSIS
 
     npm install <tarball>
 
@@ -24,7 +24,7 @@ be automatically performed some or all of the time.
 
 Installing by name and version alone is planned for the next version.
 
-See also:
+## SEE ALSO
 
 * npm help config
 * npm help activate
diff --git a/doc/link.md b/doc/link.md
index 65aeddc06..f7cc89333 100644
--- a/doc/link.md
+++ b/doc/link.md
@@ -1,8 +1,12 @@
 npm-link(1) -- Symlink a package folder
 =======================================
 
+## SYNOPSIS
+
     npm link <folder>
 
+## DESCRIPTION
+
 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
diff --git a/doc/list.md b/doc/list.md
index 81c707099..b1ed118c0 100644
--- a/doc/list.md
+++ b/doc/list.md
@@ -1,9 +1,13 @@
 npm-list(1) -- List installed packages
 ======================================
 
+## SYNOPSIS
+
     npm list [package]
     npm ls [package]
 
+## DESCRIPTION
+
 This will show the installed (and, potentially, activated) versions of all the
 packages that npm has installed, or just the `package` if specified.
 
diff --git a/doc/npm.md b/doc/npm.md
index 45ee14efb..1985b945c 100644
--- a/doc/npm.md
+++ b/doc/npm.md
@@ -1,14 +1,14 @@
 npm(1) -- node package manager
 ==============================
 
-## DESCRIPTION
-
-npm is a little package manager for the Node javascript library.
-
 ## SYNOPSIS
 
     npm <command> [args]
 
+## DESCRIPTION
+
+npm is a little package manager for the Node javascript library.
+
 Run `npm help` for more details.
 
 ## STATUS: alpha
@@ -152,5 +152,5 @@ Some "nice to have" things that aren't quite core:
 ### 0.0.7
 
 * fixed a bug in semver
-
-
+* refactor documentation
+* add "help" command
diff --git a/doc/publish.md b/doc/publish.md
index 6de79ac5d..e786d0b5a 100644
--- a/doc/publish.md
+++ b/doc/publish.md
@@ -1,7 +1,12 @@
 npm-publish(1) -- Publish a package
 ===================================
 
-    npm publish http://host.com/path/to/tarball.tgz
+
+## SYNOPSIS
+
+    npm publish <tarball-url>
+
+## DESCRIPTION
 
 Publishes a tarball containing a package to the npm registry.
 
diff --git a/doc/registry.md b/doc/registry.md
index f4e8315f8..d4be465e2 100644
--- a/doc/registry.md
+++ b/doc/registry.md
@@ -1,32 +1,17 @@
-# npm registry
+npm-registry(1) -- Notes on the JavaScript package registry
+===========================================================
 
-Notes on npm's use of the [js-registry](http://github.com/mikeal/js-registry).
-
-None of this has been implemented as of 2010-03-10.
-
-## New Commands
-
-Add the following commands:
-
-### publish
+## MARKED FOR REMOVAL
 
-    npm publish <url>
+This doc file will be removed once its contents have been implemented and its
+data moved to the relevant command documentation.
 
-Fetches the tarball from the url, checks the package.json, and sends to the
-registry as the dist url. Fails if the fetch is non-200, or if the version
-already exists in the registry for that package.
+## npm registry
 
-If the package is not already there, then publishing a tarball creates it.
-
-### tag
-
-    npm tag <project> <version> <tag>
-
-Tag a project version with a tag, anything is fine. Note that npm treats the
-"stable" tag a bit differently, preferring to install that one when not given
-a version.
+Notes on npm's use of the [js-registry](http://github.com/mikeal/js-registry).
 
-If the version doesn't exist, then it fails.
+As of 2010-04-25, the "new commands" have been added, but the changes to the
+"changed commands" have not been made yet.
 
 ## Changed commands
 
diff --git a/doc/tag.md b/doc/tag.md
index be315ef1d..bcf9cd50c 100644
--- a/doc/tag.md
+++ b/doc/tag.md
@@ -1,12 +1,15 @@
 npm-tag(1) -- Tag a published version
 =====================================
 
+## SYNOPSIS
+
     npm tag packagename 1.2.3 tagname
 
+## DESCRIPTION
+
 Tags the specified version of "packagename" with the specified "tagname".
 
 The only tag with any special significance is "stable".
 
 When installation from the registry is supported, this will be much more
 relevant.
-
diff --git a/doc/uninstall.md b/doc/uninstall.md
index 18c6942ad..4a09b554f 100644
--- a/doc/uninstall.md
+++ b/doc/uninstall.md
@@ -1,9 +1,13 @@
 npm-uninstall(1) -- Remove a package
 ====================================
 
+## SYNOPSIS
+
     npm uninstall <name> <version>
     npm rm <name> <version>
 
+## DESCRIPTION
+
 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.