[DOC] Document all configuration options (#159)

* [DOC] Convert README.rdoc to README.md for table support

* [DOC] Document all existing configuration options in a table

* [DOC] Use "-Xlint" option for JRuby native extension by default.

`javac -help -X`

> -Xlint    Enable recommended warnings

2 files changed, 147 insertions, 120 deletions

diff --git a/README.rdoc b/README.md
index 86604e7..753d9e7 100644
--- a/README.rdoc
+++ b/README.md
@@ -1,10 +1,10 @@
-= What is rake-compiler?
+# What is rake-compiler?
 
 rake-compiler is first and foremost a productivity tool for Ruby developers.
 Its goal is to make the busy developer's life easier by simplifying the building
 and packaging of Ruby extensions by simplifying code and reducing duplication.
 
-It follows *convention over configuration* by advocating a standardized build and
+It follows **convention over configuration** by advocating a standardized build and
 package structure for both C and Java based RubyGems.
 
 rake-compiler is the result of many hard-won experiences dealing with several
@@ -16,7 +16,7 @@ structure often made it very difficult for newcomers to those RubyGems.
 From these challenges, rake-compiler was born with the single-minded goal of
 making the busy RubyGem developer's life much less difficult.
 
-== Feature Overview
+## Feature Overview
 
 Some of the benefits rake-compiler provides include:
 
@@ -35,18 +35,18 @@ Some of the benefits rake-compiler provides include:
 
 * Simplifies cross platform extension compilation (targeting Windows from Linux).
 
-== OK, I'm sold! Show me how to install it!
+## OK, I'm sold! Show me how to install it!
 
 Simple:
 
-  $ gem install rake-compiler
+    $ gem install rake-compiler
 
-== That's easy. How do I use it?
+## That's easy. How do I use it?
 
 Now that you have installed rake-compiler, it's time to give your project a
 standardized structure.
 
-=== Using a standardized project structure
+### Using a standardized project structure
 
 Let's say you want to compile an extension called 'hello_world'. Organizing
 your project's code tree in the following way will help rake-compiler do
@@ -64,7 +64,7 @@ TIP: Having a consistent project directory structure will help developers and
 newcomers find and understand your code, making it easier for them to
 contribute back to your project.
 
-=== Adding the code to enable rake-compiler
+### Adding the code to enable rake-compiler
 
 Now the fun part. It's time to introduce the code to your projects Rakefile
 to tell it to use rake-compiler to build your extension:
@@ -75,7 +75,6 @@ to tell it to use rake-compiler to build your extension:
     require 'mkmf'
     create_makefile('hello_world')
 
-
     # File: Rakefile
 
     require 'rake/extensiontask'
@@ -85,8 +84,8 @@ to tell it to use rake-compiler to build your extension:
 That's it? Yes, that's it! No other lines of code are needed for
 rake-compiler to work its magic.
 
-Though, you need to make sure the parameter to <tt>create_makefile</tt>
-and <tt>ExtensionTask.new</tt> are the same or rake-compiler will not mimic
+Though, you need to make sure the parameter to `create_makefile`
+and `ExtensionTask.new` are the same or rake-compiler will not mimic
 the RubyGems standard install process. You can override this standard
 behaviour if needed, see the instructions for "non-standard project structure"
 below for details.
@@ -100,45 +99,46 @@ as easy:
 
     Rake::JavaExtensionTask.new('hello_world')
 
-=== The simple process
+### The simple process
 
-Those *two* simple lines of code automatically added the Rake tasks needed to
+Those **two** simple lines of code automatically added the Rake tasks needed to
 build your 'hello_world' extension. For example, checking the Rake tasks on
 MRI Ruby 1.8.x/1.9 returns something similar to:
 
-  $ rake -T
-  (in /home/user/my_extension)
-  rake compile                # Compile the extension(s)
-  rake compile:hello_world    # Compile just the hello_world extension
+    $ rake -T
+    (in /home/user/my_extension)
+    rake compile                # Compile the extension(s)
+    rake compile:hello_world    # Compile just the hello_world extension
 
-Simply calling <tt>compile</tt> like
+Simply calling `compile` like
 
-  $ rake compile
+    $ rake compile
 
 performs the entire compile and build process for you and places the resulting
-extension inside the <tt>lib</tt> directory of your project.
+extension inside the `lib` directory of your project.
 
-To pass <tt>dir_config</tt> options to the compilation, add to the command line:
+To pass `dir_config` options to the compilation, add to the command line:
 
-  $ rake compile -- --with-foo-[dir|lib|bin|...]=/path/to/foo
+    $ rake compile -- --with-foo-[dir|lib|bin|...]=/path/to/foo
 
 NOTE: Please be aware that building C extensions requires the proper
 development environment for your Platform, including libraries, headers
 and build tools. Check your distro / vendor documentation on how to install
 these development resources.
 
-NOTE: Building Java extensions requires the <tt>javac</tt>, part of the Java
+NOTE: Building Java extensions requires the `javac`, part of the Java
 Development Kit (JDK). This should be included by default on Mac OS X, and
 downloadable from http://java.sun.com for other operating systems.
 
-=== Generating native RubyGems
+### Generating native RubyGems
 
 A common usage scenario for rake-compiler is generating native gems that
 bundle your extensions. As mentioned above, if you have your development
 environment configured correctly, the following examples work even when
 building native gems on Windows systems.
 
-Creating native gems is really easy with rake-compiler's <tt>Rake::ExtensionTask</tt>:
+Creating native gems is really easy with rake-compiler's
+`Rake::ExtensionTask`:
 
     # somewhere in your Rakefile, define your gem spec
     spec = Gem::Specification.new do |s|
@@ -157,57 +157,57 @@ Creating native gems is really easy with rake-compiler's <tt>Rake::ExtensionTask
 As expected, you can still build your pure-ruby gem in the usual way
 (standard output) by running:
 
-  $ rake gem
-  (in /projects/oss/my_gem.git)
-  mkdir -p pkg
-    Successfully built RubyGem
-    Name: my_gem
-    Version: 0.1.0
-    File: my_gem-0.1.0.gem
-  mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
+    $ rake gem
+    (in /projects/oss/my_gem.git)
+    mkdir -p pkg
+      Successfully built RubyGem
+      Name: my_gem
+      Version: 0.1.0
+      File: my_gem-0.1.0.gem
+    mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
 
 Plus, rake-compiler tasks give you the extra functionality needed to build
 native gems by running:
 
-  # rake native gem
-  (... compilation output ...)
-  mkdir -p pkg
-    Successfully built RubyGem
-    Name: my_gem
-    Version: 0.1.0
-    File: my_gem-0.1.0.gem
-  mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
-    Successfully built RubyGem
-    Name: my_gem
-    Version: 0.1.0
-    File: my_gem-0.1.0-x86-mingw32.gem
-  mv my_gem-0.1.0-x86-mingw32.gem pkg/my_gem-0.1.0-x86-mingw32.gem
+    # rake native gem
+    (... compilation output ...)
+    mkdir -p pkg
+      Successfully built RubyGem
+      Name: my_gem
+      Version: 0.1.0
+      File: my_gem-0.1.0.gem
+    mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
+      Successfully built RubyGem
+      Name: my_gem
+      Version: 0.1.0
+      File: my_gem-0.1.0-x86-mingw32.gem
+    mv my_gem-0.1.0-x86-mingw32.gem pkg/my_gem-0.1.0-x86-mingw32.gem
 
 Did you notice that you get two gems for the price of one? How's that for a
 time saver?
 
 Similarly, it's just as easy to do the same thing for JRuby extensions:
 
-  # rake java gem
-  (... compilation output ...)
-  mkdir -p pkg
-    Successfully built RubyGem
-    Name: my_gem
-    Version: 0.1.0
-    File: my_gem-0.1.0.gem
-  mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
-    Successfully built RubyGem
-    Name: my_gem
-    Version: 0.1.0
-    File: my_gem-0.1.0-java.gem
-  mv my_gem-0.1.0-java.gem pkg/my_gem-0.1.0-java.gem
+    # rake java gem
+    (... compilation output ...)
+    mkdir -p pkg
+      Successfully built RubyGem
+      Name: my_gem
+      Version: 0.1.0
+      File: my_gem-0.1.0.gem
+    mv my_gem-0.1.0.gem pkg/my_gem-0.1.0.gem
+      Successfully built RubyGem
+      Name: my_gem
+      Version: 0.1.0
+      File: my_gem-0.1.0-java.gem
+    mv my_gem-0.1.0-java.gem pkg/my_gem-0.1.0-java.gem
 
 
-=== Great, but can I use a non-standard project structure?
+### Great, but can I use a non-standard project structure?
 
 Yes you can! While the conventional project structure is recommended, you may
 want, or need, to tweak those conventions. Rake-compiler allows you to customize
-several settings for <tt>Rake::ExtensionTask</tt>:
+several settings for `Rake::ExtensionTask`:
 
     Rake::ExtensionTask.new do |ext|
       ext.name = 'hello_world'                # indicate the name of the extension.
@@ -221,7 +221,34 @@ several settings for <tt>Rake::ExtensionTask</tt>:
                                               # will be used.
     end
 
-== Cross compilation - the future is now.
+
+### Show me all of the supported configuration options
+
+| Option               | Supported By          | Description                              |
+| -------------------- | --------------------- | ---------------------------------------- |
+| name                 | Both                  | Required. Give the target binary a name. |
+| gem_spec             | Both                  | [Optional] Indicate which gem specification will be used. |
+| tmp_dir              | Both                  | [Optional] Temporary folder used during compilation. |
+| ext_dir              | Both                  | [Optional] Where to search for `name`. Default: `ext/#{@name}`. |
+| lib_dir              | Both                  | [Optional] Put binaries into this folder. Default: `lib`. |
+| config_options       | Both                  | [Optional] Supply additional options to configure script. |
+| source_pattern       | Both                  | [Optional] Monitor file changes to allow simple rebuild. Default for CRuby: `*.{c,cc,cpp}`. Default for Java: `**/*.java`. |
+| _extra_options_      | ExtensionTask (CRuby) | [Optional] _Any options you add to ARGV on the command line are passed on as complilation flags if they begin with a dash (-)._ |
+| config_script        | ExtensionTask (CRuby) | [Optional] Specify alternate configuration file name when [Adding the code to enable rake-compiler](#adding-the-code-to-enable-rake-compiler). Default: `extconf.rb`.  |
+| cross_compile        | ExtensionTask (CRuby) | [Optional] See [Cross compilation - the future is now.](#cross-compilation---the-future-is-now) Default: `false`. |
+| cross_platform       | ExtensionTask (CRuby) | [Optional] See [Cross compilation - the future is now.](#cross-compilation---the-future-is-now) Default: `i386-mingw32`. |
+| cross_config_options | ExtensionTask (CRuby) | [Optional] See [Cross compilation - the future is now.](#cross-compilation---the-future-is-now) Default: `[]`. |
+| no_native            | ExtensionTask (CRuby) | [Optional] Set to true to prevent non-CRuby platforms from defining native tasks. Default: `false`. |
+| config_includes      | ExtensionTask (CRuby) | [Optional] Specify an Array of paths to include as `-I...:...` includes during compilation. Default: `['.']`. |
+| classpath            | JavaExtensionTask     | [Optional] Specify additional classpath paths as an Array. Default: _Uses the current CLASSPATH._  |
+| debug                | JavaExtensionTask     | [Optional] Whether to set the debug flag during complication. Default: `false`. |
+| source_version       | JavaExtensionTask     | [Optional] The JRE version that your source code requires to compile. Default: `1.6`. |
+| target_version       | JavaExtensionTask     | [Optional] The oldest JRE version you want to support. Default: `1.6`. |
+| encoding             | JavaExtensionTask     | [Optional] Specify an -encoding option to provide to the compiler. Default: `nil`. |
+| lint_option          | JavaExtensionTask     | [Optional] Specify a `-Xlint:___` linting option such as `deprecation`, `all`, `none`, etc. (Run `javac -help -X` to see all available options.) <br> Default: _Simply `-Xlint` is run, which enables recommended warnings._ |
+
+
+## Cross compilation - the future is now.
 
 Rake-compiler also provides a standardized way to generate, from either Linux
 or OSX, extensions and gem binaries for your Windows users!
@@ -230,9 +257,9 @@ How can this be you say? Simple, rake-compiler's cross compilation features
 take advantage of GCC's host/target capabilities to build 'target' binaries on
 different 'host' OS's.
 
-=== How do I do this from Linux or OSX?
+### How do I do this from Linux or OSX?
 
-==== The Easy Way
+#### The Easy Way
 
 Use rake-compiler-dock, a gem that makes use of a virtual machine provisioned with
 all the necessary build tools.  You can add a task to your Rakefile, that
@@ -240,17 +267,17 @@ cross-compiles and packages your gem into Windows fat binaries (with 1.8 to 2.2
 and x86/x64 support). See https://github.com/rake-compiler/rake-compiler-dock for more
 information.
 
-==== The Manual Way
+#### The Manual Way
 
 In addition to having the development tool chain installed (GCC), you also need to
-install your platform's <tt>mingw32</tt> cross compilation package.
+install your platform's `mingw32` cross compilation package.
 
 Installation depends upon your operating system/distribution. On Ubuntu and Debian
-host machines, a simple <tt>apt-get install mingw32</tt> will be enough.
+host machines, a simple `apt-get install mingw32` will be enough.
 
-On Arch, <tt>mingw32</tt> is installed by running <tt>pacman -S mingw32-gcc</tt>
+On Arch, `mingw32` is installed by running `pacman -S mingw32-gcc`
 
-On OSX, we no longer recommend the usage of MacPorts <tt>mingw32</tt> package because
+On OSX, we no longer recommend the usage of MacPorts `mingw32` package because
 it stagnated in GCC version 3.4.5.
 
 Instead we recommend you download mingw-w64 automated build packages available at
@@ -258,56 +285,56 @@ SourceForge:
 
 http://sourceforge.net/downloads/mingw-w64/
 
-Browse into <em>Toolchains targetting Win32</em> and then <em>Automated Builds</em>.
+Browse into *Toolchains targetting Win32* and then *Automated Builds*.
 
 Files will be ordered by recency, find the latest one with version 1.0 in it,
 like this one:
 
-  mingw-w32-1.0-bin_i686-darwin_20110422.tar.bz2
+    mingw-w32-1.0-bin_i686-darwin_20110422.tar.bz2
 
 Download and extract. After that, make sure the bin directory is added to the PATH, eg:
 
-  export PATH=~/mingw-w64/w32/bin:$PATH
+    export PATH=~/mingw-w64/w32/bin:$PATH
 
-You can add this to your <tt>.profile</tt> to avoid the repitition.
+You can add this to your `.profile` to avoid the repitition.
 
-==== I've got my tool-chain installed, now what?
+#### I've got my tool-chain installed, now what?
 
 First, you need to build Ruby for Windows on your Linux or OSX system.
 
 Relax, no need to freak out! Let rake-compiler do all the heavy lifting for you:
 
-  rake-compiler cross-ruby
+    rake-compiler cross-ruby
 
 And you're done. It will automatically download, configure and compile the latest
-stable version of Ruby for Windows, and place it into your <tt>~/.rake-compiler</tt>
+stable version of Ruby for Windows, and place it into your `~/.rake-compiler`
 directory.
 
-This will create <tt>~/.rake-compiler/config.yml</tt> file so that rake-compiler
-knows where to find the <tt>rbconfig.rb</tt> file that matches the Ruby version
+This will create `~/.rake-compiler/config.yml` file so that rake-compiler
+knows where to find the `rbconfig.rb` file that matches the Ruby version
 on the Windows host system you're cross-compiling for. An example:
 
-  # File: ~/.rake-compiler/config.yml
+    # File: ~/.rake-compiler/config.yml
 
-  rbconfig-x86-mingw32-1.8.6: /path/to/ruby-1.8.6/rbconfig.rb
-  rbconfig-x86-mingw32-1.8.7: /path/to/ruby-1.8.7/rbconfig.rb
-  rbconfig-x86-mingw32-1.9.2: /path/to/ruby-1.9.2/rbconfig.rb
+    rbconfig-x86-mingw32-1.8.6: /path/to/ruby-1.8.6/rbconfig.rb
+    rbconfig-x86-mingw32-1.8.7: /path/to/ruby-1.8.7/rbconfig.rb
+    rbconfig-x86-mingw32-1.9.2: /path/to/ruby-1.9.2/rbconfig.rb
 
 If, instead, you want to build a different Ruby version than the default one, please
-supply a <tt>VERSION</tt>:
+supply a `VERSION`:
 
-  rake-compiler cross-ruby VERSION=1.8.6-p114
+    rake-compiler cross-ruby VERSION=1.8.6-p114
 
 If you, like me, have multiple versions of MinGW packages installed, you can
 specify the HOST that will be used to cross compile Ruby:
 
-  rake-compiler cross-ruby HOST=x86-mingw32 # (OSX mingw32 port)
+    rake-compiler cross-ruby HOST=x86-mingw32 # (OSX mingw32 port)
 
 The host will vary depending on provider (mingw32 versus mingw-w64 projects).
 Please consult the documentation and website of the MinGW package provider before
 reporting any issues.
 
-==== OK, let's cross compile some gems!
+#### OK, let's cross compile some gems!
 
 Now, you only need specify a few additional options in your extension definition:
 
@@ -338,53 +365,53 @@ Now, you only need specify a few additional options in your extension definition
 
 By default, cross compilation targets 'i386-mingw32' which is the default
 GCC platform for Ruby. MRI Ruby's current official distribution uses
-<tt>i386-mswin32-60</tt>. The RubyInstaller distribution uses
-<tt>x86-mingw32</tt> and <tt>x64-mingw32</tt> for 32-bit and 64-bit
-Windows targets, respectively. Note that <tt>i386</tt> and <tt>x86</tt>
-are synonymous here; <tt>x86</tt> is preferred going forward.
+`i386-mswin32-60`. The RubyInstaller distribution uses
+`x86-mingw32` and `x64-mingw32` for 32-bit and 64-bit
+Windows targets, respectively. Note that `i386` and `x86`
+are synonymous here; `x86` is preferred going forward.
 
-The format for <tt>cross_config_options</tt> is an array of strings and
-hashes. Hashes will be fetched for each value of <tt>cross_platform</tt>
+The format for `cross_config_options` is an array of strings and
+hashes. Hashes will be fetched for each value of `cross_platform`
 as the build iterates, or ignored if there is no value for that platform.
 You can mix-and-match strings and hashes to get desired option ordering.
 
-==== Warning, magician about to do some tricks, don't blink!
+#### Warning, magician about to do some tricks, don't blink!
 
 Cross compiling is still very simple:
 
-  rake cross compile
+    rake cross compile
 
 And now, building gems for your Windows users is just 6 more letters:
 
-  rake cross native gem
+    rake cross native gem
 
 And you're done, yeah.
 
-==== But wait, there's more
+#### But wait, there's more
 
 You can specify which version of Ruby to build the extension against:
 
-  rake cross compile RUBY_CC_VERSION=1.8.6
+    rake cross compile RUBY_CC_VERSION=1.8.6
 
-For example, if you installed <tt>1.9.2</tt>, you can do:
+For example, if you installed `1.9.2`, you can do:
 
-  rake cross compile RUBY_CC_VERSION=1.9.2
+    rake cross compile RUBY_CC_VERSION=1.9.2
 
 Even better, you can target multiple versions (ie. 1.8.6 and 1.9.2) in
 the same gem via:
 
-  rake cross compile RUBY_CC_VERSION=1.8.6:1.9.2
+    rake cross compile RUBY_CC_VERSION=1.8.6:1.9.2
 
 And better yet, you can bundle both binary extensions into one so-called "fat"
 gem via:
 
-  rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.2
+    rake cross native gem RUBY_CC_VERSION=1.8.6:1.9.2
 
 That will place binaries for both the 1.8 and 1.9 versions of your Ruby
-extensions inside your project's <tt>lib_dir</tt> directory:
+extensions inside your project's `lib_dir` directory:
 
-  lib/1.8/my_extension.so
-  lib/1.9/my_extension.so
+    lib/1.8/my_extension.so
+    lib/1.9/my_extension.so
 
 NOTE: building "fat" gems is currently only supported by rake-compiler when
 cross compiling from a Linux or OSX host. Patches are welcome if building
@@ -392,12 +419,12 @@ cross compiling from a Linux or OSX host. Patches are welcome if building
 
 Now it's up to you to make your gem load the proper binary at runtime:
 
-  begin
-    RUBY_VERSION =~ /(\d+\.\d+)/
-    require "#{$1}/my_extension"
-  rescue LoadError
-    require "my_extension"
-  end
+    begin
+      RUBY_VERSION =~ /(\d+\.\d+)/
+      require "#{$1}/my_extension"
+    rescue LoadError
+      require "my_extension"
+    end
 
 The above technique will lookup first for 1.8 or 1.9 version of the extension
 and when not found, will look for the plain extension.
@@ -406,7 +433,7 @@ This approach catch the cases of provided fat binaries or gems compiled by the
 end user installing the gem. It has also been implemented successfully in
 several projects.
 
-== What are you talking about? (Give me examples)
+## What are you talking about? (Give me examples)
 
 I know all the above sounds like a complete foreign language (it does even for me!).
 So, what if I show you some examples?
@@ -416,19 +443,19 @@ projects and how they use rake-compiler.
 
 http://github.com/rake-compiler/rake-compiler/wiki/projects-using-rake-compiler
 
-== Future
+## Future
 
 rake-compiler is a work in progress and we appreciate any and all feedback
 during the development of it! (and contributions too!)
 
 You can find more information about rake-compiler:
 
-* GitHub:    https://github.com/rake-compiler/rake-compiler
-* Issues:    https://github.com/rake-compiler/rake-compiler/issues
-* Docs:      http://rubydoc.info/gems/rake-compiler
-* Wiki:      https://github.com/rake-compiler/rake-compiler/wiki
+*   GitHub:    https://github.com/rake-compiler/rake-compiler
+*   Issues:    https://github.com/rake-compiler/rake-compiler/issues
+*   Docs:      http://rubydoc.info/gems/rake-compiler
+*   Wiki:      https://github.com/rake-compiler/rake-compiler/wiki
 
-== Disclaimer
+## Disclaimer
 
 If you have any trouble, don't hesitate to contact the author. As always,
 I'm not going to say "Use at your own risk" because I don't want this library
diff --git a/rake-compiler.gemspec b/rake-compiler.gemspec
index 755dd21..daeffc0 100644
--- a/rake-compiler.gemspec
+++ b/rake-compiler.gemspec
@@ -30,7 +30,7 @@ Gem::Specification.new do |s|
   s.files += Dir.glob("spec/**/*.rb")
   s.files += Dir.glob("tasks/**/*.rake")
   s.files += ["Rakefile", "Gemfile"]
-  s.files += Dir.glob("*.{rdoc,txt,yml}")
+  s.files += Dir.glob("*.{md,rdoc,txt,yml}")
 
   s.bindir      = 'bin'
   s.executables = ['rake-compiler']
@@ -38,9 +38,9 @@ Gem::Specification.new do |s|
   s.require_path = 'lib'
 
   # documentation
-  s.rdoc_options << '--main'  << 'README.rdoc' << '--title' << 'rake-compiler -- Documentation'
+  s.rdoc_options << '--main'  << 'README.md' << '--title' << 'rake-compiler -- Documentation'
 
-  s.extra_rdoc_files = %w(README.rdoc LICENSE.txt History.txt)
+  s.extra_rdoc_files = %w(README.md LICENSE.txt History.txt)
 
   # project information
   s.homepage          = 'https://github.com/rake-compiler/rake-compiler'