embeditor-rails 1.1.1 → 2.0.0.beta

data/lib/node_modules/npm/doc/misc/npm-developers.md

@@ -0,0 +1,207 @@
+npm-developers(7) -- Developer Guide
+====================================
+
+## DESCRIPTION
+
+So, you've decided to use npm to develop (and maybe publish/deploy)
+your project.
+
+Fantastic!
+
+There are a few things that you need to do above the simple steps
+that your users will do to install your program.
+
+## About These Documents
+
+These are man pages.  If you install npm, you should be able to
+then do `man npm-thing` to get the documentation on a particular
+topic, or `npm help thing` to see the same information.
+
+## What is a `package`
+
+A package is:
+
+* a) a folder containing a program described by a package.json file
+* b) a gzipped tarball containing (a)
+* c) a url that resolves to (b)
+* d) a `<name>@<version>` that is published on the registry with (c)
+* e) a `<name>@<tag>` that points to (d)
+* f) a `<name>` that has a "latest" tag satisfying (e)
+* g) a `git` url that, when cloned, results in (a).
+
+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).
+
+Git urls can be of the form:
+
+    git://github.com/user/project.git#commit-ish
+    git+ssh://user@hostname:project.git#commit-ish
+    git+http://user@hostname/project/blah.git#commit-ish
+    git+https://user@hostname/project/blah.git#commit-ish
+
+The `commit-ish` can be any tag, sha, or branch which can be supplied as
+an argument to `git checkout`.  The default is `master`.
+
+## The package.json File
+
+You need to have a `package.json` file in the root of your project to do
+much of anything with npm.  That is basically the whole interface.
+
+See `package.json(5)` for details about what goes in that file.  At the very
+least, you need:
+
+* name:
+  This should be a string that identifies your project.  Please do not
+  use the name to specify that it runs on node, or is in JavaScript.
+  You can use the "engines" field to explicitly state the versions of
+  node (or whatever else) that your program requires, and it's pretty
+  well assumed that it's javascript.
+
+  It does not necessarily need to match your github repository name.
+
+  So, `node-foo` and `bar-js` are bad names.  `foo` or `bar` are better.
+
+* version:
+  A semver-compatible version.
+
+* engines:
+  Specify the versions of node (or whatever else) that your program
+  runs on.  The node API changes a lot, and there may be bugs or new
+  functionality that you depend on.  Be explicit.
+
+* author:
+  Take some credit.
+
+* scripts:
+  If you have a special compilation or installation script, then you
+  should put it in the `scripts` hash.  You should definitely have at
+  least a basic smoke-test command as the "scripts.test" field.
+  See npm-scripts(7).
+
+* main:
+  If you have a single module that serves as the entry point to your
+  program (like what the "foo" package gives you at require("foo")),
+  then you need to specify that in the "main" field.
+
+* directories:
+  This is a hash of folders.  The best ones to include are "lib" and
+  "doc", but if you specify a folder full of man pages in "man", then
+  they'll get installed just like these ones.
+
+You can use `npm init` in the root of your package in order to get you
+started with a pretty basic package.json file.  See `npm-init(1)` for
+more info.
+
+## Keeping files *out* of your package
+
+Use a `.npmignore` file to keep stuff out of your package.  If there's
+no `.npmignore` file, but there *is* a `.gitignore` file, then npm will
+ignore the stuff matched by the `.gitignore` file.  If you *want* to
+include something that is excluded by your `.gitignore` file, you can
+create an empty `.npmignore` file to override it.
+
+By default, the following paths and files are ignored, so there's no
+need to add them to `.npmignore` explicitly:
+
+* `.*.swp`
+* `._*`
+* `.DS_Store`
+* `.git`
+* `.hg`
+* `.lock-wscript`
+* `.svn`
+* `.wafpickle-*`
+* `CVS`
+* `npm-debug.log`
+
+Additionally, everything in `node_modules` is ignored, except for
+bundled dependencies. npm automatically handles this for you, so don't
+bother adding `node_modules` to `.npmignore`.
+
+The following paths and files are never ignored, so adding them to
+`.npmignore` is pointless:
+
+* `package.json`
+* `README.*`
+
+## Link Packages
+
+`npm link` is designed to install a development package and see the
+changes in real time without having to keep re-installing it.  (You do
+need to either re-link or `npm rebuild -g` to update compiled packages,
+of course.)
+
+More info at `npm-link(1)`.
+
+## Before Publishing: Make Sure Your Package Installs and Works
+
+**This is important.**
+
+If you can not install it locally, you'll have
+problems trying to publish it.  Or, worse yet, you'll be able to
+publish it, but you'll be publishing a broken or pointless package.
+So don't do that.
+
+In the root of your package, do this:
+
+    npm install . -g
+
+That'll show you that it's working.  If you'd rather just create a symlink
+package that points to your working directory, then do this:
+
+    npm link
+
+Use `npm ls -g` to see if it's there.
+
+To test a local install, go into some other folder, and then do:
+
+    cd ../some-other-folder
+    npm install ../my-package
+
+to install it locally into the node_modules folder in that other place.
+
+Then go into the node-repl, and try using require("my-thing") to
+bring in your module's main module.
+
+## Create a User Account
+
+Create a user with the adduser command.  It works like this:
+
+    npm adduser
+
+and then follow the prompts.
+
+This is documented better in npm-adduser(1).
+
+## Publish your package
+
+This part's easy.  IN the root of your folder, do this:
+
+    npm publish
+
+You can give publish a url to a tarball, or a filename of a tarball,
+or a path to a folder.
+
+Note that pretty much **everything in that folder will be exposed**
+by default.  So, if you have secret stuff in there, use a
+`.npmignore` file to list out the globs to ignore, or publish
+from a fresh checkout.
+
+## Brag about it
+
+Send emails, write blogs, blab in IRC.
+
+Tell the world how easy it is to install your program!
+
+## SEE ALSO
+
+* npm-faq(7)
+* npm(1)
+* npm-init(1)
+* package.json(5)
+* npm-scripts(7)
+* npm-publish(1)
+* npm-adduser(1)
+* npm-registry(7)

data/lib/node_modules/npm/doc/misc/npm-disputes.md

@@ -0,0 +1,99 @@
+npm-disputes(7) -- Handling Module Name Disputes
+================================================
+
+## SYNOPSIS
+
+1. Get the author email with `npm owner ls <pkgname>`
+2. Email the author, CC <support@npmjs.com>
+3. After a few weeks, if there's no resolution, we'll sort it out.
+
+Don't squat on package names.  Publish code or move out of the way.
+
+## DESCRIPTION
+
+There sometimes arise cases where a user publishes a module, and then
+later, some other user wants to use that name.  Here are some common
+ways that happens (each of these is based on actual events.)
+
+1. Joe writes a JavaScript module `foo`, which is not node-specific.
+   Joe doesn't use node at all.  Bob   wants to use `foo` in node, so he
+   wraps it in an npm module.  Some time later, Joe starts using node,
+   and wants to take over management of his program.
+2. Bob writes an npm module `foo`, and publishes it.  Perhaps much
+   later, Joe finds a bug in `foo`, and fixes it.  He sends a pull
+   request to Bob, but Bob doesn't have the time to deal with it,
+   because he has a new job and a new baby and is focused on his new
+   erlang project, and kind of not involved with node any more.  Joe
+   would like to publish a new `foo`, but can't, because the name is
+   taken.
+3. Bob writes a 10-line flow-control library, and calls it `foo`, and
+   publishes it to the npm registry.  Being a simple little thing, it
+   never really has to be updated.  Joe works for Foo Inc, the makers
+   of the critically acclaimed and widely-marketed `foo` JavaScript
+   toolkit framework.  They publish it to npm as `foojs`, but people are
+   routinely confused when `npm install foo` is some different thing.
+4. Bob writes a parser for the widely-known `foo` file format, because
+   he needs it for work.  Then, he gets a new job, and never updates the
+   prototype.  Later on, Joe writes a much more complete `foo` parser,
+   but can't publish, because Bob's `foo` is in the way.
+
+The validity of Joe's claim in each situation can be debated.  However,
+Joe's appropriate course of action in each case is the same.
+
+1. `npm owner ls foo`.  This will tell Joe the email address of the
+   owner (Bob).
+2. Joe emails Bob, explaining the situation **as respectfully as
+   possible**, and what he would like to do with the module name.  He
+   adds the npm support staff <support@npmjs.com> to the CC list of
+   the email.  Mention in the email that Bob can run `npm owner add
+   joe foo` to add Joe as an owner of the `foo` package.
+3. After a reasonable amount of time, if Bob has not responded, or if
+   Bob and Joe can't come to any sort of resolution, email support
+   <support@npmjs.com> and we'll sort it out.  ("Reasonable" is
+   usually at least 4 weeks, but extra time is allowed around common
+   holidays.)
+
+## REASONING
+
+In almost every case so far, the parties involved have been able to reach
+an amicable resolution without any major intervention.  Most people
+really do want to be reasonable, and are probably not even aware that
+they're in your way.
+
+Module ecosystems are most vibrant and powerful when they are as
+self-directed as possible.  If an admin one day deletes something you
+had worked on, then that is going to make most people quite upset,
+regardless of the justification.  When humans solve their problems by
+talking to other humans with respect, everyone has the chance to end up
+feeling good about the interaction.
+
+## EXCEPTIONS
+
+Some things are not allowed, and will be removed without discussion if
+they are brought to the attention of the npm registry admins, including
+but not limited to:
+
+1. Malware (that is, a package designed to exploit or harm the machine on
+   which it is installed).
+2. Violations of copyright or licenses (for example, cloning an
+   MIT-licensed program, and then removing or changing the copyright and
+   license statement).
+3. Illegal content.
+4. "Squatting" on a package name that you *plan* to use, but aren't
+   actually using.  Sorry, I don't care how great the name is, or how
+   perfect a fit it is for the thing that someday might happen.  If
+   someone wants to use it today, and you're just taking up space with
+   an empty tarball, you're going to be evicted.
+5. Putting empty packages in the registry.  Packages must have SOME
+   functionality.  It can be silly, but it can't be *nothing*.  (See
+   also: squatting.)
+6. Doing weird things with the registry, like using it as your own
+   personal application database or otherwise putting non-packagey
+   things into it.
+
+If you see bad behavior like this, please report it right away.
+
+## SEE ALSO
+
+* npm-registry(7)
+* npm-owner(1)

data/lib/node_modules/npm/doc/misc/npm-faq.md

@@ -0,0 +1,364 @@
+npm-faq(7) -- Frequently Asked Questions
+========================================
+
+## Where can I find these docs in HTML?
+
+<https://www.npmjs.org/doc/>, or run:
+
+    npm config set viewer browser
+
+to open these documents in your default web browser rather than `man`.
+
+## It didn't work.
+
+That's not really a question.
+
+## Why didn't it work?
+
+I don't know yet.
+
+Read the error output, and if you can't figure out what it means,
+do what it says and post a bug with all the information it asks for.
+
+## Where does npm put stuff?
+
+See `npm-folders(5)`
+
+tl;dr:
+
+* Use the `npm root` command to see where modules go, and the `npm bin`
+  command to see where executables go
+* Global installs are different from local installs.  If you install
+  something with the `-g` flag, then its executables go in `npm bin -g`
+  and its modules go in `npm root -g`.
+
+## How do I install something on my computer in a central location?
+
+Install it globally by tacking `-g` or `--global` to the command.  (This
+is especially important for command line utilities that need to add
+their bins to the global system `PATH`.)
+
+## I installed something globally, but I can't `require()` it
+
+Install it locally.
+
+The global install location is a place for command-line utilities
+to put their bins in the system `PATH`.  It's not for use with `require()`.
+
+If you `require()` a module in your code, then that means it's a
+dependency, and a part of your program.  You need to install it locally
+in your program.
+
+## Why can't npm just put everything in one place, like other package managers?
+
+Not every change is an improvement, but every improvement is a change.
+This would be like asking git to do network IO for every commit.  It's
+not going to happen, because it's a terrible idea that causes more
+problems than it solves.
+
+It is much harder to avoid dependency conflicts without nesting
+dependencies.  This is fundamental to the way that npm works, and has
+proven to be an extremely successful approach.  See `npm-folders(5)` for
+more details.
+
+If you want a package to be installed in one place, and have all your
+programs reference the same copy of it, then use the `npm link` command.
+That's what it's for.  Install it globally, then link it into each
+program that uses it.
+
+## Whatever, I really want the old style 'everything global' style.
+
+Write your own package manager.  You could probably even wrap up `npm`
+in a shell script if you really wanted to.
+
+npm will not help you do something that is known to be a bad idea.
+
+## Should I check my `node_modules` folder into git?
+
+Mikeal Rogers answered this question very well:
+
+<http://www.mikealrogers.com/posts/nodemodules-in-git.html>
+
+tl;dr
+
+* Check `node_modules` into git for things you **deploy**, such as
+  websites and apps.
+* Do not check `node_modules` into git for libraries and modules
+  intended to be reused.
+* Use npm to manage dependencies in your dev environment, but not in
+  your deployment scripts.
+
+## Is it 'npm' or 'NPM' or 'Npm'?
+
+npm should never be capitalized unless it is being displayed in a
+location that is customarily all-caps (such as the title of man pages.)
+
+## If 'npm' is an acronym, why is it never capitalized?
+
+Contrary to the belief of many, "npm" is not in fact an abbreviation for
+"Node Package Manager".  It is a recursive bacronymic abbreviation for
+"npm is not an acronym".  (If it was "ninaa", then it would be an
+acronym, and thus incorrectly named.)
+
+"NPM", however, *is* an acronym (more precisely, a capitonym) for the
+National Association of Pastoral Musicians.  You can learn more
+about them at <http://npm.org/>.
+
+In software, "NPM" is a Non-Parametric Mapping utility written by
+Chris Rorden.  You can analyze pictures of brains with it.  Learn more
+about the (capitalized) NPM program at <http://www.cabiatl.com/mricro/npm/>.
+
+The first seed that eventually grew into this flower was a bash utility
+named "pm", which was a shortened descendent of "pkgmakeinst", a
+bash function that was used to install various different things on different
+platforms, most often using Yahoo's `yinst`.  If `npm` was ever an
+acronym for anything, it was `node pm` or maybe `new pm`.
+
+So, in all seriousness, the "npm" project is named after its command-line
+utility, which was organically selected to be easily typed by a right-handed
+programmer using a US QWERTY keyboard layout, ending with the
+right-ring-finger in a postition to type the `-` key for flags and
+other command-line arguments.  That command-line utility is always
+lower-case, though it starts most sentences it is a part of.
+
+## How do I list installed packages?
+
+`npm ls`
+
+## How do I search for packages?
+
+`npm search`
+
+Arguments are greps.  `npm search jsdom` shows jsdom packages.
+
+## How do I update npm?
+
+    npm update npm -g
+
+You can also update all outdated local packages by doing `npm update` without
+any arguments, or global packages by doing `npm update -g`.
+
+Occasionally, the version of npm will progress such that the current
+version cannot be properly installed with the version that you have
+installed already.  (Consider, if there is ever a bug in the `update`
+command.)
+
+In those cases, you can do this:
+
+    curl https://npmjs.org/install.sh | sh
+
+## What is a `package`?
+
+A package is:
+
+* a) a folder containing a program described by a package.json file
+* b) a gzipped tarball containing (a)
+* c) a url that resolves to (b)
+* d) a `<name>@<version>` that is published on the registry with (c)
+* e) a `<name>@<tag>` that points to (d)
+* f) a `<name>` that has a "latest" tag satisfying (e)
+* g) a `git` url that, when cloned, results in (a).
+
+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).
+
+Git urls can be of the form:
+
+    git://github.com/user/project.git#commit-ish
+    git+ssh://user@hostname:project.git#commit-ish
+    git+http://user@hostname/project/blah.git#commit-ish
+    git+https://user@hostname/project/blah.git#commit-ish
+
+The `commit-ish` can be any tag, sha, or branch which can be supplied as
+an argument to `git checkout`.  The default is `master`.
+
+## What is a `module`?
+
+A module is anything that can be loaded with `require()` in a Node.js
+program.  The following things are all examples of things that can be
+loaded as modules:
+
+* A folder with a `package.json` file containing a `main` field.
+* A folder with an `index.js` file in it.
+* A JavaScript file.
+
+Most npm packages are modules, because they are libraries that you
+load with `require`.  However, there's no requirement that an npm
+package be a module!  Some only contain an executable command-line
+interface, and don't provide a `main` field for use in Node programs.
+
+Almost all npm packages (at least, those that are Node programs)
+*contain* many modules within them (because every file they load with
+`require()` is a module).
+
+In the context of a Node program, the `module` is also the thing that
+was loaded *from* a file.  For example, in the following program:
+
+    var req = require('request')
+
+we might say that "The variable `req` refers to the `request` module".
+
+## So, why is it the "`node_modules`" folder, but "`package.json`" file?  Why not `node_packages` or `module.json`?
+
+The `package.json` file defines the package.  (See "What is a
+package?" above.)
+
+The `node_modules` folder is the place Node.js looks for modules.
+(See "What is a module?" above.)
+
+For example, if you create a file at `node_modules/foo.js` and then
+had a program that did `var f = require('foo.js')` then it would load
+the module.  However, `foo.js` is not a "package" in this case,
+because it does not have a package.json.
+
+Alternatively, if you create a package which does not have an
+`index.js` or a `"main"` field in the `package.json` file, then it is
+not a module.  Even if it's installed in `node_modules`, it can't be
+an argument to `require()`.
+
+## `"node_modules"` is the name of my deity's arch-rival, and a Forbidden Word in my religion.  Can I configure npm to use a different folder?
+
+No.  This will never happen.  This question comes up sometimes,
+because it seems silly from the outside that npm couldn't just be
+configured to put stuff somewhere else, and then npm could load them
+from there.  It's an arbitrary spelling choice, right?  What's the big
+deal?
+
+At the time of this writing, the string `'node_modules'` appears 151
+times in 53 separate files in npm and node core (excluding tests and
+documentation).
+
+Some of these references are in node's built-in module loader.  Since
+npm is not involved **at all** at run-time, node itself would have to
+be configured to know where you've decided to stick stuff.  Complexity
+hurdle #1.  Since the Node module system is locked, this cannot be
+changed, and is enough to kill this request.  But I'll continue, in
+deference to your deity's delicate feelings regarding spelling.
+
+Many of the others are in dependencies that npm uses, which are not
+necessarily tightly coupled to npm (in the sense that they do not read
+npm's configuration files, etc.)  Each of these would have to be
+configured to take the name of the `node_modules` folder as a
+parameter.  Complexity hurdle #2.
+
+Furthermore, npm has the ability to "bundle" dependencies by adding
+the dep names to the `"bundledDependencies"` list in package.json,
+which causes the folder to be included in the package tarball.  What
+if the author of a module bundles its dependencies, and they use a
+different spelling for `node_modules`?  npm would have to rename the
+folder at publish time, and then be smart enough to unpack it using
+your locally configured name.  Complexity hurdle #3.
+
+Furthermore, what happens when you *change* this name?  Fine, it's
+easy enough the first time, just rename the `node_modules` folders to
+`./blergyblerp/` or whatever name you choose.  But what about when you
+change it again?  npm doesn't currently track any state about past
+configuration settings, so this would be rather difficult to do
+properly.  It would have to track every previous value for this
+config, and always accept any of them, or else yesterday's install may
+be broken tomorrow.  Complexity hurdle #5.
+
+Never going to happen.  The folder is named `node_modules`.  It is
+written indelibly in the Node Way, handed down from the ancient times
+of Node 0.3.
+
+## How do I install node with npm?
+
+You don't.  Try one of these node version managers:
+
+Unix:
+
+* <http://github.com/isaacs/nave>
+* <http://github.com/visionmedia/n>
+* <http://github.com/creationix/nvm>
+
+Windows:
+
+* <http://github.com/marcelklehr/nodist>
+* <https://github.com/hakobera/nvmw>
+* <https://github.com/nanjingboy/nvmw>
+
+## How can I use npm for development?
+
+See `npm-developers(7)` and `package.json(5)`.
+
+You'll most likely want to `npm link` your development folder.  That's
+awesomely handy.
+
+To set up your own private registry, check out `npm-registry(7)`.
+
+## Can I list a url as a dependency?
+
+Yes.  It should be a url to a gzipped tarball containing a single folder
+that has a package.json in its root, or a git url.
+(See "what is a package?" above.)
+
+## How do I symlink to a dev folder so I don't have to keep re-installing?
+
+See `npm-link(1)`
+
+## The package registry website.  What is that exactly?
+
+See `npm-registry(7)`.
+
+## I forgot my password, and can't publish.  How do I reset it?
+
+Go to <https://npmjs.org/forgot>.
+
+## I get ECONNREFUSED a lot.  What's up?
+
+Either the registry is down, or node's DNS isn't able to reach out.
+
+To check if the registry is down, open up
+<https://registry.npmjs.org/> in a web browser.  This will also tell
+you if you are just unable to access the internet for some reason.
+
+If the registry IS down, let us know by emailing <support@npmjs.com>
+or posting an issue at <https://github.com/npm/npm/issues>.  If it's
+down for the world (and not just on your local network) then we're
+probably already being pinged about it.
+
+You can also often get a faster response by visiting the #npm channel
+on Freenode IRC.
+
+## Why no namespaces?
+
+Please see this discussion: <https://github.com/npm/npm/issues/798>
+
+tl;dr - It doesn't actually make things better, and can make them worse.
+
+If you want to namespace your own packages, you may: simply use the
+`-` character to separate the names.  npm is a mostly anarchic system.
+There is not sufficient need to impose namespace rules on everyone.
+
+## Who does npm?
+
+npm was originally written by Isaac Z. Schlueter, and many others have
+contributed to it, some of them quite substantially.
+
+The npm open source project, The npm Registry, and [the community
+website](https://www.npmjs.org) are maintained and operated by the
+good folks at [npm, Inc.](https://www.npmjs.com)
+
+## I have a question or request not addressed here. Where should I put it?
+
+Post an issue on the github project:
+
+* <https://github.com/npm/npm/issues>
+
+## Why does npm hate me?
+
+npm is not capable of hatred.  It loves everyone, especially you.
+
+## SEE ALSO
+
+* npm(1)
+* npm-developers(7)
+* package.json(5)
+* npm-config(1)
+* npm-config(7)
+* npmrc(5)
+* npm-config(7)
+* npm-folders(5)