Use mdtoc for the readme

README.md

@@ -36,7 +36,18 @@ tools that do one thing well.
     of executing arbitrary code, rbenv reads just the version name
     from each project. There's nothing to "trust."
 
-## How It Works
+   * [1 How It Works](#section_1)
+   * [2 Installation](#section_2)
+   * [3 Usage](#section_3)
+      * [3.1 set-default](#section_3.1)
+      * [3.2 set-local](#section_3.2)
+      * [3.3 versions](#section_3.3)
+      * [3.4 version](#section_3.4)
+      * [3.5 rehash](#section_3.5)
+   * [4 Contributing](#section_4)
+      * [4.1 License](#section_4.1)
+
+## <a name="section_1">1</a> How It Works
 
 rbenv operates on the per-user directory `~/.rbenv`. Version names in
 rbenv correspond to subdirectories of `~/.rbenv/versions`. For
@@ -56,7 +67,7 @@ and then execute the corresponding binary.
 Because of the simplicity of the shim approach, all you need to use
 rbenv is `~/.rbenv/shims` in your `$PATH`.
 
-## Installation
+## <a name="section_2">2</a> Installation
 
 rbenv is a young project, so for now you must install it from source.
 
@@ -103,32 +114,36 @@ when installing a gem that provides a binary).
 
         $ rbenv rehash
 
-## Usage
+## <a name="section_3">3</a> Usage
 
 Like `git`, the `rbenv` command delegates to subcommands based on its
 first argument. The most common subcommands are:
 
-* **set-default** — sets the default version of Ruby to be used in all
+### <a name="section_3.1">3.1</a> set-default
-    shells by writing the version name to the `~/.rbenv/default`
+
-    file. This version can be overridden by a per-project
+Sets the default version of Ruby to be used in all shells by writing
-    `.rbenv-version` file, or by setting the `RBENV_VERSION`
+the version name to the `~/.rbenv/default` file. This version can be
-    environment variable.
+overridden by a per-project `.rbenv-version` file, or by setting the
+`RBENV_VERSION` environment variable.
 
     $ rbenv set-default 1.9.2-p290
 
-    The special version name `system` tells rbenv to use the system
+The special version name `system` tells rbenv to use the system Ruby
-    Ruby (detected by searching your `$PATH`).
+(detected by searching your `$PATH`).
 
-* **set-local** — sets a local per-project Ruby version by writing the
+### <a name="section_3.2">3.2</a> set-local
-    version name to an `.rbenv-version` file in the current
+
-    directory. This version overrides the default, and can be
+Sets a local per-project Ruby version by writing the version name to
-    overridden itself by setting the `RBENV_VERSION` environment
+an `.rbenv-version` file in the current directory. This version
-    variable.
+overrides the default, and can be overridden itself by setting the
+`RBENV_VERSION` environment variable.
 
     $ rbenv set-local rbx-1.2.4
 
-* **versions** — lists all Ruby versions known to rbenv, and shows an
+### <a name="section_3.3">3.3</a> versions
-    asterisk next to the currently active version.
+
+Lists all Ruby versions known to rbenv, and shows an asterisk next to
+the currently active version.
 
     $ rbenv versions
       1.8.7-p352
@@ -138,20 +153,23 @@ first argument. The most common subcommands are:
       rbx-1.2.4
       ree-1.8.7-2011.03
 
-* **version** — displays the currently active Ruby version, along with
+### <a name="section_3.4">3.4</a> version
-    information on how it was set.
+
+Displays the currently active Ruby version, along with information on
+how it was set.
 
     $ rbenv version
     1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version)
 
-* **rehash** — installs shims for all Ruby binaries known to rbenv
+### <a name="section_3.5">3.5</a> rehash
-    (i.e., `~/.rbenv/versions/*/bin/*`). Run this command after you
+
-    install a new version of Ruby, or install a gem that provides
+Installs shims for all Ruby binaries known to rbenv (i.e.,
-    binaries.
+`~/.rbenv/versions/*/bin/*`). Run this command after you install a new
+version of Ruby, or install a gem that provides binaries.
 
     $ rbenv rehash
 
-## Contributing
+## <a name="section_4">4</a> Contributing
 
 The rbenv source code is [hosted on
 GitHub](https://github.com/sstephenson/rbenv). It's clean, modular,
@@ -160,7 +178,7 @@ and easy to understand, even if you're not a shell hacker.
 Please feel free to submit pull requests and file bugs on the [issue
 tracker](https://github.com/sstephenson/rbenv/issues).
 
-## License
+### <a name="section_4.1">4.1</a> License
 
 (The MIT license)
 

doc/README.mdtoc

@@ -0,0 +1,193 @@
+# Simple Ruby Version Management: rbenv
+
+<img src="http://cloud.github.com/downloads/sstephenson/rbenv/rbenv.png" width="894" height="464">
+
+rbenv lets you easily switch between multiple versions of Ruby. It's
+simple, unobtrusive, and follows the UNIX tradition of single-purpose
+tools that do one thing well.
+
+### rbenv _does…_
+
+* Let you **change the default Ruby version** on a per-user basis.
+* Provide support for **per-project Ruby versions**.
+* Allow you to **override the Ruby version** with an environment
+  variable.
+
+### In contrast with rvm, rbenv _does not…_
+
+* **Need to be loaded into your shell.** Instead, rbenv's shim
+    approach works by adding a directory to your `$PATH`.
+* **Override shell commands like `cd`.** That's just obnoxious!
+* **Have a configuration file.** There's nothing to configure except
+    which version of Ruby you want to use.
+* **Install Ruby.** You can build and install Ruby yourself, or use
+    [ruby-build](https://github.com/sstephenson/ruby-build.git) to
+    automate the process.
+* **Manage gemsets.** [Bundler](http://gembundler.com/) is a better
+    way to manage application dependencies. If you have projects that
+    are not yet using Bundler you can install the
+    [rbenv-gemset](https://github.com/jamis/rbenv-gemset) plugin.
+* **Require changes to Ruby libraries for compatibility.** The
+    simplicity of rbenv means as long as it's in your `$PATH`,
+    [nothing](https://rvm.beginrescueend.com/integration/bundler/)
+    [else](https://rvm.beginrescueend.com/integration/capistrano/)
+    needs to know about it.
+* **Prompt you with warnings when you switch to a project.** Instead
+    of executing arbitrary code, rbenv reads just the version name
+    from each project. There's nothing to "trust."
+
+## How It Works ##
+
+rbenv operates on the per-user directory `~/.rbenv`. Version names in
+rbenv correspond to subdirectories of `~/.rbenv/versions`. For
+example, you might have `~/.rbenv/versions/1.8.7-p354` and
+`~/.rbenv/versions/1.9.3-preview1`.
+
+Each version is a working tree with its own binaries, like
+`~/.rbenv/versions/1.8.7-p354/bin/ruby` and
+`~/.rbenv/versions/1.9.3-preview1/irb`. rbenv makes _shim binaries_
+for every such binary across all installed versions of Ruby.
+
+These shims are simple wrapper scripts that live in `~/.rbenv/shims`
+and detect which Ruby version you want to use. They insert the
+directory for the selected version at the beginning of your `$PATH`
+and then execute the corresponding binary.
+
+Because of the simplicity of the shim approach, all you need to use
+rbenv is `~/.rbenv/shims` in your `$PATH`.
+
+## Installation ##
+
+rbenv is a young project, so for now you must install it from source.
+
+**Compatibility note**: rbenv is _incompatible_ with rvm. Things will
+  appear to work until you try to install a gem. The problem is that
+  rvm actually overrides the `gem` command with a shell function!
+  Please remove any references to rvm before using rbenv.
+
+1. Check out rbenv into `~/.rbenv`.
+
+        $ cd
+        $ git clone git://github.com/sstephenson/rbenv.git .rbenv
+
+2. Add `~/.rbenv/bin` to your `$PATH` for access to the `rbenv`
+command-line utility.
+
+        $ echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> .bash_profile
+
+3. Add rbenv's shims directory to your `$PATH` and set up Bash
+autocompletion. (If you prefer not to load rbenv in your shell, you
+can manually add `$HOME/.rbenv/shims` to your path in step 2.)
+
+        $ echo 'eval "$(rbenv init -)"' >> .bash_profile
+
+4. Restart your shell. You can now begin using rbenv.
+
+        $ exec
+
+5. Install Ruby versions into `~/.rbenv/versions`. For example, to
+install Ruby 1.9.2-p290, download and unpack the source, then run:
+
+        $ ./configure --prefix=~/.rbenv/versions/1.9.2-p290
+        $ make
+        $ make install
+
+    The [ruby-build](https://github.com/sstephenson/ruby-build)
+    project simplifies this process to a single command:
+
+        $ ruby-build 1.9.2-p290 ~/.rbenv/versions/1.9.2-p290
+
+6. Rebuild the shim binaries. You should do this any time you install
+a new Ruby binary (for example, when installing a new Ruby version, or
+when installing a gem that provides a binary).
+
+        $ rbenv rehash
+
+## Usage ##
+
+Like `git`, the `rbenv` command delegates to subcommands based on its
+first argument. The most common subcommands are:
+
+### set-default ###
+
+Sets the default version of Ruby to be used in all shells by writing
+the version name to the `~/.rbenv/default` file. This version can be
+overridden by a per-project `.rbenv-version` file, or by setting the
+`RBENV_VERSION` environment variable.
+
+    $ rbenv set-default 1.9.2-p290
+
+The special version name `system` tells rbenv to use the system Ruby
+(detected by searching your `$PATH`).
+
+### set-local ###
+
+Sets a local per-project Ruby version by writing the version name to
+an `.rbenv-version` file in the current directory. This version
+overrides the default, and can be overridden itself by setting the
+`RBENV_VERSION` environment variable.
+
+    $ rbenv set-local rbx-1.2.4
+
+### versions ###
+
+Lists all Ruby versions known to rbenv, and shows an asterisk next to
+the currently active version.
+
+    $ rbenv versions
+      1.8.7-p352
+      1.9.2-p290
+    * 1.9.3-preview1 (set by /Users/sam/.rbenv/default)
+      jruby-1.6.3
+      rbx-1.2.4
+      ree-1.8.7-2011.03
+
+### version ###
+
+Displays the currently active Ruby version, along with information on
+how it was set.
+
+    $ rbenv version
+    1.8.7-p352 (set by /Volumes/37signals/basecamp/.rbenv-version)
+
+### rehash ###
+
+Installs shims for all Ruby binaries known to rbenv (i.e.,
+`~/.rbenv/versions/*/bin/*`). Run this command after you install a new
+version of Ruby, or install a gem that provides binaries.
+
+    $ rbenv rehash
+
+## Contributing ##
+
+The rbenv source code is [hosted on
+GitHub](https://github.com/sstephenson/rbenv). It's clean, modular,
+and easy to understand, even if you're not a shell hacker.
+
+Please feel free to submit pull requests and file bugs on the [issue
+tracker](https://github.com/sstephenson/rbenv/issues).
+
+### License ###
+
+(The MIT license)
+
+Copyright (c) 2011 Sam Stephenson
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

doc/build

@@ -0,0 +1,4 @@
+#!/bin/sh -e
+
+ruby mdtoc.rb README.mdtoc > ../README.md
+

doc/mdtoc.rb

@@ -0,0 +1,82 @@
+#!/usr/bin/env ruby
+
+# A little Markdown filter that scans your document for headings,
+# numbers them, adds anchors, and inserts a table of contents.
+#
+# To use it, make sure the headings you want numbered and linked are
+# in this format:
+#
+#     ### Title ###
+#
+# I.e. they must have an equal number of octothorpes around the title
+# text. (In Markdown, `#` means `h1`, `##` means `h2`, and so on.)
+# The table of contents will be inserted before the first such
+# heading.
+#
+# Released into the public domain.
+# Sam Stephenson <sstephenson@gmail.com>
+# 2011-04-30
+
+def mdtoc(markdown)
+  titles = []
+  lines = markdown.split($/)
+  start = nil
+
+  # First pass: Scan the Markdown source looking for titles of the
+  # format: `### Title ###`. Record the line number, header level
+  # (number of octothorpes), and text of each matching title.
+  lines.each_with_index do |line, line_no|
+    if line.match(/^(\#{1,6})\s+(.+?)\s+\1$/)
+      titles << [line_no, $1.length, $2]
+      start ||= line_no
+    end
+  end
+
+  last_section = nil
+  last_level = nil
+
+  # Second pass: Iterate over all matched titles and compute their
+  # corresponding section numbers. Then replace the titles with
+  # annotated anchors.
+  titles.each do |title_info|
+    line_no, level, text = title_info
+
+    if last_section
+      section = last_section.dup
+
+      if last_level < level
+        section << 1
+      else
+        (last_level - level).times { section.pop }
+        section[-1] += 1
+      end
+    else
+      section = [1]
+    end
+
+    name = section.join(".")
+    lines[line_no] = %(#{"#" * level} <a name="section_#{name}">#{name}</a> #{text})
+
+    title_info << section
+    last_section = section
+    last_level = level
+  end
+
+  # Third pass: Iterate over matched titles once more to produce the
+  # table of contents. Then insert it immediately above the first
+  # matched title.
+  if start
+    toc = titles.map do |(line_no, level, text, section)|
+      name = section.join(".")
+      %(#{" " * (section.length * 3)}* [#{name} #{text}](#section_#{name}))
+    end + [""]
+
+    lines.insert(start, *toc)
+  end
+
+  lines.join("\n")
+end
+
+if __FILE__ == $0
+  puts mdtoc($<.read)
+end