Move the man pages to the bundler repository and write a build task to convert them into roff and txt format.

3 files changed, 641 insertions, 0 deletions

diff --git a/man/bundle-install.ronn b/man/bundle-install.ronn
new file mode 100644
index 00000000..22234758
--- /dev/null
+++ b/man/bundle-install.ronn
@@ -0,0 +1,310 @@
+bundle-install(1) -- Install the dependencies specified in your Gemfile
+=======================================================================
+
+## SYNOPSIS
+
+`bundle install` [--local] [--quiet] [--gemfile=GEMFILE] [--system]
+                 [--deployment] [--frozen] [--path]
+                 [--binstubs[=DIRECTORY]] [--without=GROUP1[ GROUP2...]]
+
+## DESCRIPTION
+
+Install the gems specified in your `Gemfile(7)`. If this is the first
+time you run bundle install (and a `Gemfile.lock` does not exist),
+bundler will fetch all remote sources, resolve dependencies and
+install all needed gems.
+
+If a `Gemfile.lock` does exist, and you have not updated your `Gemfile`,
+bundler will fetch all remote sources, but use the dependencies
+specified in the `Gemfile.lock` instead of resolving dependencies.
+
+If a `Gemfile.lock` does exist, and you have updated your `Gemfile`,
+bundler will use the dependencies in the `Gemfile.lock` for all gems
+that you did not update, but will re-resolve the dependencies of
+gems that you did update. You can find more information about this
+update process below under [CONSERVATIVE UPDATING][].
+
+## OPTIONS
+
+* `--gemfile=<gemfile>`:
+  The location of the `Gemfile` that bundler should use. This defaults
+  to a gemfile in the current working directory. In general, bundler
+  will assume that the location of the `Gemfile` is also the project
+  root, and will look for the `Gemfile.lock` and `vendor/cache` relative
+  to it.
+
+* `--path=<path>`:
+  The location to install the gems in the bundle to. This defaults
+  to the gem home, which is the location that `gem install` installs
+  gems to. This means that, by default, gems installed without a
+  `--path` setting will show up in `gem list`. This setting is a
+  [remembered option][REMEMBERED OPTIONS].
+
+* `--system`:
+  Installs the gems in the bundle to the system location. This
+  overrides any previous [remembered][REMEMBERED OPTIONS] use of
+  `--path`.
+
+* `--without=<list>`:
+  A space-separated list of groups to skip installing. This is a
+  [remembered option][REMEMBERED OPTIONS].
+
+* `--local`:
+  Do not attempt to connect to `rubygems.org`, instead using just
+  the gems located in `vendor/cache`. Note that if a more
+  appropriate platform-specific gem exists on `rubygems.org`,
+  this will bypass the normal lookup.
+
+* `--deployment`:
+  Switches bundler's defaults into [deployment mode][DEPLOYMENT MODE].
+
+* `--binstubs[=<directory>]`:
+  Create a directory (defaults to `bin`) containing an executable
+  that runs in the context of the bundle. For instance, if the
+  `rails` gem comes with a `rails` executable, this flag will create
+  a `bin/rails` executable that ensures that all dependencies used
+  come from the bundled gems.
+
+## DEPLOYMENT MODE
+
+Bundler's defaults are optimized for development. To switch to
+defaults optimized for deployment, use the `--deployment` flag.
+
+1. A `Gemfile.lock` is required.
+
+   To ensure that the same versions of the gems you developed with 
+   and tested with are also used in deployments, a `Gemfile.lock`
+   is required.
+
+   This is mainly to ensure that you remember to check your 
+   `Gemfile.lock` into version control.
+
+2. The `Gemfile.lock` must be up to date
+
+   In development, you can modify your `Gemfile` and re-run
+   `bundle install` to [conservatively update][CONSERVATIVE UPDATING]
+   your `Gemfile.lock` snapshot.
+
+   In deployment, your `Gemfile.lock` should be up-to-date with
+   changes made in your `Gemfile`.
+
+3. Gems are installed to `vendor/bundle` not your default system location
+
+   In development, it's convenient to share the gems used in your
+   application with other applications and other scripts run on
+   the system.
+
+   In deployment, isolation is a more important default. In addition,
+   the user deploying the application may not have permission to install
+   gems to the system, or the web server may not have permission to
+   read them.
+
+   As a result, `bundle install --deployment` installs gems to
+   the `vendor/bundle` directory in the application. This may be
+   overridden using the `--path` option.
+
+## SUDO USAGE
+
+By default, bundler installs gems to the same location as `gem install`.
+
+In some cases, that location may not be writable by your Unix user. In
+that case, bundler will stage everything in a temporary directory,
+then ask you for your `sudo` password in order to copy the gems into
+their system location.
+
+From your perspective, this is identical to installing them gems
+directly into the system.
+
+You should never use `sudo bundle install`. This is because several
+other steps in `bundle install` must be performed as the current user:
+
+* Updating your `Gemfile.lock`
+* Updating your `vendor/cache`, if necessary
+* Checking out private git repositories using your user's SSH keys
+
+Of these three, the first two could theoretically be performed by
+`chown`ing the resulting files to `$SUDO_USER`. The third, however,
+can only be performed by actually invoking the `git` command as
+the current user.
+
+As a result, you should run `bundle install` as the current user,
+and bundler will ask for your password if it is needed to perform
+the final step.
+
+## INSTALLING GROUPS
+
+By default, `bundle install` will install all gems in all groups
+in your `Gemfile(7)`, except those declared for a different platform.
+
+However, you can explicitly tell bundler to skip installing
+certain groups with the `--without` option. This option takes
+a space-separated list of groups.
+
+While the `--without` option will skip _installing_ the gems in the 
+specified groups, it will still _download_ those gems and use them to
+resolve the dependencies of every gem in your `Gemfile`.
+
+This is so that installing a different set of groups on another
+ machine (such as a production server) will not change the
+gems and versions that you have already developed and tested against.
+
+`Bundler offers a rock-solid guarantee that the third-party
+code you are running in development and testing is also the
+third-party code you are running in production. You can choose
+to exclude some of that code in different environments, but you
+will never be caught flat-footed by different versions of
+third-party code being used in different environments.`
+
+For a simple illustration, consider the following `Gemfile`:
+
+    source "http://rubygems.org"
+
+    gem "sinatra"
+
+    group :production do
+      gem "rack-perftools-profiler"
+    end
+
+In this case, `sinatra` depends on any version of Rack (`>= 1.0`, while
+`rack-perftools-profiler` depends on 1.x (`~> 1.0`).
+
+When you run `bundle install --without production` in development, we
+look at the dependencies of `rack-perftools-profiler` as well. That way,
+you do not spend all your time developing against Rack 2.0, using new
+APIs unavailable in Rack 1.x, only to have bundler switch to Rack 1.2
+when the `production` group _is_ used.
+
+This should not cause any problems in practice, because we do not
+attempt to `install` the gems in the excluded groups, and only evaluate
+as part of the dependency resolution process.
+
+This also means that you cannot include different versions of the same
+gem in different groups, because doing so would result in different
+sets of dependencies used in development and production. Because of
+the vagaries of the dependency resolution process, this usually
+affects more than just the gems you list in your `Gemfile`, and can
+(surprisingly) radically change the gems you are using.
+
+## REMEMBERED OPTIONS
+
+Some options (marked above in the [OPTIONS][] section) are remembered
+between calls to `bundle install`, and by the Bundler runtime.
+
+For instance, if you run `bundle install --without test`, a subsequent
+call to `bundle install` that does not include a `--without` flag will
+remember your previous choice.
+
+In addition, a call to `Bundler.setup` will not attempt to make the
+gems in those groups available on the Ruby load path, as they were
+not installed.
+
+The settings that are remembered are:
+
+* `--deployment`:
+  At runtime, this remembered setting will also result in Bundler
+  raising an exception if the `Gemfile.lock` is out of date.
+
+* `--path`:
+  Subsequent calls to `bundle install` will install gems to the
+  directory originally passed to `--path`. The Bundler runtime
+  will look for gems in that location. You can revert this
+  option by running `bundle install --system`.
+
+* `--binstubs`:
+  Bundler will update the executables every subsequent call to
+  `bundle install`.
+
+* `--without`:
+  As described above, Bundler will skip the gems specified by
+  `--without` in subsequent calls to `bundle install`. The
+  Bundler runtime will also not try to make the gems in the
+  skipped groups available.
+
+## THE GEMFILE.LOCK
+
+When you run `bundle install`, Bundler will persist the full names
+and versions of all gems that you used (including dependencies of
+the gems specified in the `Gemfile`) into a file called `Gemfile.lock`.
+
+Bundler uses this file in all subsequent calls to `bundle install`,
+which guarantees that you always use the same exact code, even
+as your application moves across machines.
+
+Because of the way dependency resolution works, even a
+seemingly small change (for instance, an update to a point-release
+of a dependency of a gem in your `Gemfile`) can result in radically
+different gems being needed to satisfy all dependencies.
+
+As a result, you `SHOULD` check your `Gemfile.lock` into version
+control. If you do not, every machine that checks out your
+repository (including your production server) will resolve all
+dependencies again, which will result in different versions of
+third-party code being used if `any` of the gems in the `Gemfile`
+or any of their dependencies have been updated.
+
+## CONSERVATIVE UPDATING
+
+When you make a change to the `Gemfile` and then run `bundle install`,
+Bundler will update only the gems that you modified.
+
+In other words, if a gem that you `did not modify` worked before
+you called `bundle install`, it will continue to use the exact
+same versions of all dependencies as it used before the update.
+
+Let's take a look at an example. Here's your original `Gemfile`:
+
+    source "http://rubygems.org"
+
+    gem "actionpack", "2.3.8"
+    gem "activemerchant"
+
+In this case, both `actionpack` and `activemerchant` depend on
+`activesupport`. The `actionpack` gem depends on `activesupport 2.3.8`
+and `rack ~> 1.1.0`, while the `activemerchant` gem depends on 
+`activesupport >= 2.3.2`, `braintree >= 2.0.0`, and `builder >= 2.0.0`.
+
+When the dependencies are first resolved, Bundler will select
+`activesupport 2.3.8`, which satisfies the requirements of both
+gems in your `Gemfile`.
+
+Next, you modify your `Gemfile` to:
+
+    source "http://rubygems.org"
+
+    gem "actionpack", "3.0.0.rc"
+    gem "activemerchant"
+
+The `actionpack 3.0.0.rc` gem has a number of new dependencies,
+and updates the `activesupport` dependency to `= 3.0.0.rc` and
+the `rack` dependency to `~> 1.2.1`.
+
+When you run `bundle install`, Bundler notices that you changed
+the `actionpack` gem, but not the `activemerchant` gem. It
+evaluates the gems currently being used to satisfy its requirements:
+
+  * `activesupport 2.3.8`:
+    also used to satisfy a dependency in `activemerchant`,
+    which is not being updated
+  * `rack ~> 1.1.0`:
+    not currently being used to satify another dependency
+
+Because you did not explicitly ask to update `activemerchant`,
+you would not expect it to suddenly stop working after updating
+`actionpack`. However, satisfying the new `activesupport 3.0.0.rc`
+dependency of actionpack requires updating one of its dependencies.
+
+Even though `activemerchant` declares a very loose dependency
+that theoretically matches `activesupport 3.0.0.rc`, bundler treats
+gems in your `Gemfile` that have not changed as an atomic unit
+together with their dependencies. In this case, the `activemerchant`
+dependency is treated as `activemerchant 1.7.1 + activesupport 2.3.8`,
+so `bundle install` will report that it cannot update `actionpack`.
+
+To explicitly update `actionpack`, including its dependencies
+which other gems in the `Gemfile` still depend on, run
+`bundle update actionpack` (see `bundle update(1)`).
+
+`Summary`: In general, after making a change to the `Gemfile`, you
+should first try to run `bundle install`, which will guarantee that no
+other gems in the `Gemfile` are impacted by the change. If that
+does not work, run `bundle update(1)`.
diff --git a/man/bundle.ronn b/man/bundle.ronn
new file mode 100644
index 00000000..48ea209c
--- /dev/null
+++ b/man/bundle.ronn
@@ -0,0 +1,77 @@
+bundle(1) -- Ruby Dependency Management
+=======================================
+
+## SYNOPSIS
+
+`bundle` [--no-color] COMMAND [ARGS]
+
+## DESCRIPTION
+
+Bundler manages an `application's dependencies` through its entire life
+across many machines systematically and repeatably.
+
+See [the bundler website](http://gembundler.com) for information on getting
+started, and `Gemfile(7)` for more information on the `Gemfile` format.
+
+## OPTIONS
+
+* `--no-color`:
+  Prints all output without color
+
+## BUNDLE COMMANDS
+
+We divide `bundle` subcommands into primary commands and utilities.
+
+## PRIMARY COMMANDS
+
+* `bundle install(1)`:
+  Install the gems specified by the `Gemfile` or `Gemfile.lock`
+
+* `bundle update(1)`:
+  Update dependencies to their latest versions
+
+* `bundle package(1)`:
+  Package the .gem files required by your application into the
+  `vendor/cache` directory
+
+* `bundle exec(1)`:
+  Execute a script in the context of the current bundle
+
+* `bundle config(1)`:
+  Specify and read configuration options for bundler
+
+## UTILITIES
+
+* `bundle check(1)`:
+  Determine whether the requirements for your application are installed
+  and available to bundler
+
+* `bundle list(1)`:
+  Show all of the gems in the current bundle
+
+* `bundle show(1)`:
+  Show the source location of a particular gem in the bundle
+
+* `bundle console(1)`:
+  Start an IRB session in the context of the current bundle
+
+* `bundle open(1)`:
+  Open an installed gem in the editor
+
+* `bundle viz(1)`:
+  Generate a visual representation of your dependencies
+
+* `bundle init(1)`:
+  Generate a simple `Gemfile`, placed in the current directory
+
+* `bundle gem(1)`:
+  Create a simple gem, suitable for development with bundler
+
+## OBSOLOETE
+
+These commands are obsolete and should no longer be used
+
+* `bundle lock(1)`
+* `bundle unlock(1)`
+* `bundle cache(1)`
+
diff --git a/man/gemfile.5.ronn b/man/gemfile.5.ronn
new file mode 100644
index 00000000..a7152eeb
--- /dev/null
+++ b/man/gemfile.5.ronn
@@ -0,0 +1,254 @@
+Gemfile(5) -- A format for describing gem dependencies for Ruby programs
+========================================================================
+
+## SYNOPSIS
+
+A `Gemfile` describes the gem dependencies required to execute associated
+Ruby code.
+
+Place the `Gemfile` in the root of the directory containing the associated
+code. For instance, in a Rails application, place the `Gemfile` in the same
+directory as the `Rakefile`.
+
+## SYNTAX
+
+A `Gemfile` is evaluated as Ruby code, in a context which makes available
+a number of methods used to describe the gem requirements.
+
+## SOURCES (#source)
+
+At the top of the `Gemfile`, add one line for each `Rubygems` source that
+might contain the gems listed in the `Gemfile`.
+
+    source "http://rubygems.org"
+    source "http://gems.github.com"
+
+Each of these _source_s `MUST` be a valid Rubygems repository.
+
+## GEMS (#gem)
+
+Specify gem requirements using the `gem` method, with the following arguments.
+All parameters are `OPTIONAL` unless otherwise specified.
+
+### NAME (required)
+
+For each gem requirement, list a single _gem_ line.
+
+    gem "nokogiri"
+
+### VERSION
+
+Each _gem_ `MAY` have one or more version specifiers.
+
+    gem "nokogiri", ">= 1.4.2"
+    gem "RedCloth", ">= 4.1.0", "< 4.2.0"
+
+### REQUIRE AS (:require)
+
+Each _gem_ `MAY` specify its main file, which should be used when autorequiring
+(`Bundler.require`).
+
+    gem "sqlite3-ruby", :require => "sqlite3"
+
+This defaults to the name of the gem itself. For instance, these are identical:
+
+    gem "nokogiri"
+    gem "nokogiri", :require => "nokogiri"
+
+### GROUPS (:group or :groups)
+
+Each _gem_ `MAY` specify membership in one or more groups. Any _gem_ that does
+not specify membership in any group is placed in the `default` group.
+
+    gem "rspec", :group => :test
+    gem "wirble", :groups => [:development, :test]
+
+The Bundler runtime allows its two main methods, `Bundler.setup` and
+`Bundler.require`, to limit their impact to particular groups.
+
+    # setup adds gems to Ruby's load path
+    Bundler.setup                    # defaults to all groups
+    require "bundler/setup"          # same as Bundler.setup
+    Bundler.setup(:default)          # only set up the _default_ group
+    Bundler.setup(:test)             # only set up the _test_ group (but `not` _default_)
+    Bundler.setup(:default, :test)   # set up the _default_ and _test_ groups, but no others
+
+    # require requires all of the gems in the specified groups
+    Bundler.require                  # defaults to just the _default_ group
+    Bundler.require(:default)        # identical
+    Bundler.require(:default, :test) # requires the _default_ and _test_ groups
+    Bundler.require(:test)           # requires just the _test_ group
+
+The Bundler CLI allows you to specify a list of groups whose gems `bundle install` should
+not install with the `--without` option. To specify multiple groups to ignore, specify a
+list of groups separated by spaces.
+
+    bundle install --without test
+    bundle install --without development test
+
+After running `bundle install --without test`, bundler will remember that you excluded
+the test group in the last installation. The next time you run `bundle install`, 
+without any `--without option`, bundler will recall it.
+
+Also, calling `Bundler.setup` with no parameters, or calling `require "bundler/setup"`
+will setup all groups except for the ones you excluded via `--without` (since they
+are obviously not available).
+
+Note that on `bundle install`, bundler downloads and evaluates all gems, in order to
+create a single canonical list of all of the required gems and their dependencies.
+This means that you cannot list different versions of the same gems in different
+groups. For more details, see [Understanding Bundler](http://gembundler.com/v1.0/understanding.html).
+
+### PLATFORMS (:platforms)
+
+If a gem should only be used in a particular platform or set of platforms, you can 
+specify them. Platforms are essentially identical to groups, except that you do not
+need to use the `--without` install-time flag to exclude groups of gems for other
+platforms.
+
+There are a number of `Gemfile` platforms:
+
+  * `ruby`:
+    C Ruby (MRI) or Rubinius, but `NOT` Windows
+  * `ruby_18`:
+    _ruby_ `AND` version 1.8
+  * `ruby_19`:
+    _ruby_ `AND` version 1.9
+  * `mri`:
+    Same as _ruby_, but not Rubinius
+  * `mri_18`:
+    _mri_ `AND` version 1.8
+  * `mri_19`:
+    _mri_ `AND` version 1.9
+  * `jruby`:
+    JRuby
+  * `mswin`:
+    Windows
+
+As with groups, you can specify one or more platforms:
+
+    gem "weakling",   :platforms => :jruby
+    gem "ruby-debug", :platforms => :mri_18
+    gem "nokogiri",   :platforms => [:mri_18, :jruby]
+
+All operations involving groups (`bundle install`, `Bundler.setup`,
+`Bundler.require`) behave exactly the same as if any groups not
+matching the current platform were explicitly excluded.
+
+### GIT (:git)
+
+If necessary, you can specify that a gem is located at a particular
+git repository. The repository can be public (`http://github.com/rails/rails.git`)
+or private (`git@github.com:rails/rails.git`). If the repository is private,
+the user that you use to run `bundle install` `MUST` have the appropriate
+keys available in their `$HOME/.ssh`.
+
+Git repositories are specified using the `:git` parameter. The `group`,
+`platforms`, and `require` options are available and behave exactly the same
+as they would for a normal gem.
+
+    gem "rails", :git => "git://github.com/rails/rails.git"
+
+A git repository `SHOULD` have at least one file, at the root of the
+directory containing the gem, with the extension `.gemspec`. This file
+`MUST` contain a valid gem specification, as expected by the `gem build`
+command. It `MUST NOT` have any dependencies, other than on the files in
+the git repository itself and any built-in functionality of Ruby or Rubygems.
+
+If a git repository does not have a `.gemspec`, bundler will attempt to
+create one, but it will not contain any dependencies, executables, or
+C extension compilation instructions. As a result, it may fail to properly
+integrate into your application.
+
+If a git repository does have a `.gemspec` for the gem you attached it
+to, a version specifier, if provided, means that the git repository is
+only valid if the `.gemspec` specifies a version matching the version
+specifier. If not, bundler will print a warning.
+
+    gem "rails", "2.3.8", :git => "git://github.com/rails/rails.git"
+    # bundle install will fail, because the .gemspec in the rails
+    # repository's master branch specifies version 3.0.0
+
+If a git repository does `not` have a `.gemspec` for the gem you attached
+it to, a version specifier `MUST` be provided. Bundler will use this
+version in the simple `.gemspec` it creates.
+
+Git repositories support a number of additional options.
+
+  * `branch`, `tag`, and `ref`:
+    You `MUST` only specify at most one of these options. The default
+    is `:branch => "master"`
+  * `submodules`:
+    Specify `:submodules => true` to cause bundler to expand any
+    submodules included in the git repository
+
+If a git repository contains multiple `.gemspecs`, each `.gemspec`
+represents a gem located at the same place in the file system as
+the `.gemspec`.
+
+    |~rails                   [git root]
+    | |-rails.gemspec         [rails gem located here]
+    |~actionpack
+    | |-actionpack.gemspec    [actionpack gem located here]
+    |~activesupport
+    | |-activesupport.gemspec [activesupport gem located here]
+    ...
+
+To install a gem located in a git repository, bundler changes to
+the directory containing the gemspec, runs `gem build name.gemspec`
+and then installs the resulting gem. The `gem build` command,
+which comes standard with Rubygems, evaluates the `.gemspec` in
+the context of the directory in which it is located.
+
+### PATH (:path)
+
+You can specify that a gem is located in a particular location
+on the file system. Relative paths are resolved relative to the
+directory containing the `Gemfile`.
+
+Similar to the semantics of the `:git` option, the `:path`
+option requires that the directory in question either contains
+a `.gemspec` for the gem, or that you specify an explicit
+version that bundler should use.
+
+Unlike `:git`, bundler does not compile C extensions for
+gems specified as paths.
+
+    gem "rails", :path => "vendor/rails"
+
+## BLOCK FORM OF GIT, PATH, GROUP and PLATFORMS
+
+The `:git`, `:path`, `:group`, and `:platforms` options may be
+applied to a group of gems by using block form.
+
+    git "git://github.com/rails/rails.git" do
+      gem "activesupport"
+      gem "actionpack"
+    end
+
+    platforms :ruby do
+      gem "ruby-debug"
+      gem "sqlite3-ruby"
+    end
+
+    group :development do
+      gem "wirble"
+      gem "faker"
+    end
+
+In the case of the `git` block form, the `:ref`, `:branch`, `:tag`,
+and `:submodules` options may be passed to the `git` method, and
+all gems in the block will inherit those options.
+
+## SOURCE PRIORITY
+
+When attempting to locate a gem to satisfy a gem requirement,
+bundler uses the following priority order:
+
+  1. The source explicitly attached to the gem (using `:path` or `:git`)
+  2. For implicit gems (dependencies of explicit gems), any git or path
+     repository otherwise declared. This results in bundler prioritizing the
+     ActiveSupport gem from the Rails git repository over ones from
+     `rubygems.org`
+  3. The sources specified via `source`, in the order in which they were
+     declared in the `Gemfile`.