[chore] Tidy markdown formatting for consistency

(cherry picked from commit 3e58600)

Author: chadlwilson

README.md

@@ -27,16 +27,18 @@ in your WAR file when it gets built.
 If you're assembling your own WAR using other means, you can install the
 **jruby-rack** gem. It provides a method to locate the jar file:
 
-    require 'jruby-rack'
-    FileUtils.cp JRubyJars.jruby_rack_jar_path, '.'
+```ruby
+require 'jruby-rack'
+FileUtils.cp JRubyJars.jruby_rack_jar_path, '.'
+```
 
 Otherwise you'll need to download the latest [jar release][2], drop it into the
-*WEB-INF/lib* directory and configure the `RackFilter` in your application's
-*web.xml* (see following examples).
+`WEB-INF/lib` directory and configure the `RackFilter` in your application's
+`web.xml` (see following examples).
 
 ### Rails
 
-Here's sample *web.xml* configuration for Rails. Note the environment and
+Here's sample `web.xml` configuration for Rails. Note the environment and
 min/max runtime parameters. For **multi-threaded** (a.k.a. `threadsafe!`)
 Rails with a single runtime, set min/max both to 1. Otherwise, define the size
 of the runtime pool as you wish.
@@ -85,8 +87,8 @@ of the runtime pool as you wish.
 ### (Other) Rack Applications
 
 The main difference when using a non-Rails Rack application is that JRuby-Rack
-looks for a "rackup" file named **config.ru** in  `WEB-INF/config.ru` or
-`WEB-INF/*/config.ru`. Here's a sample *web.xml* configuration :
+looks for a "rackup" file named `config.ru` in  `WEB-INF/config.ru` or
+`WEB-INF/*/config.ru`. Here's a sample `web.xml` configuration :
 
 ```xml
 <filter>
@@ -104,8 +106,8 @@ looks for a "rackup" file named **config.ru** in  `WEB-INF/config.ru` or
 </listener>
 ```
 
-If you don't have a *config.ru* or don't want to include it in your web app, you
-can embed it directly in the *web.xml* as follows (using Sinatra as an example):
+If you don't have a `config.ru` or don't want to include it in your web app, you
+can embed it directly in the `web.xml` as follows (using Sinatra as an example):
 
 ```xml
 <context-param>
@@ -140,7 +142,11 @@ using is `org.jruby.rack.RackFilter`, the filter supports the following
   gets reset (accepts  values "true", "false" and "buffer" to reset the buffer
   only), by default "true"
 - **addsHtmlToPathInfo** controls whether the .html suffix is added to the URI
-  when checking if the request is for a static page
+  when checking if the request is for a static page. The default behavior for 
+  Rails and many other Ruby applications is to add an `.html` extension to the 
+  resource and attempt to handle it before serving a dynamic request on the 
+  original URI.  However, this behavior may confuse other servlets in your 
+  application that have a wildcard mapping. Defaults to true.
 - **verifiesHtmlResource** used with the previous parameter to make sure the
   requested static resource exists before adding the .html request URI suffix
 
@@ -150,9 +156,9 @@ a filter, the servlet class name is `org.jruby.rack.RackServlet`.
 ## Servlet Environment Integration
 
 - servlet context is accessible to any application through the Rack environment
-  variable *java.servlet_context* (as well as the `$servlet_context` global).
+  variable `java.servlet_context` (as well as the `$servlet_context` global).
 - the (native) servlet request and response objects could be obtained via the
-  *java.servlet_request* and *java.servlet_response* keys
+  `java.servlet_request` and `java.servlet_response` keys
 - all servlet request attributes are passed through to the Rack environment (and
   thus might override request headers or Rack environment variables)
 - servlet sessions can be used as a (java) session store for Rails, session
@@ -171,16 +177,15 @@ Several aspects of Rails are automatically set up for you.
 ## JRuby Runtime Management
 
 JRuby runtime management and pooling is done automatically by the framework.
-In the case of Rails, runtimes are pooled by default (the default will most
-likely change with the adoption of Rails 4.0). For other Rack applications a
+In the case of Rails, runtimes are pooled by default. For other Rack applications a
 single shared runtime is created and shared for every request by default.
-If *jruby.min.runtimes* and *jruby.max.runtimes* values are
+If `jruby.min.runtimes` and `jruby.max.runtimes` values are
 specified pooling is supported for plain Rack applications as well.
 
 We do recommend to boot your runtimes up-front to avoid the cost of initializing
 one while a request kicks in and find the pool empty, this can be easily avoided
-by setting *jruby.min.runtimes* equal to *jruby.max.runtimes*. You might also
-want to consider tuning the *jruby.runtime.acquire.timeout* parameter to not
+by setting `jruby.min.runtimes` equal to `jruby.max.runtimes`. You might also
+want to consider tuning the `jruby.runtime.acquire.timeout` parameter to not
 wait too long when all (max) runtimes from the pool are busy.
 
 ## JRuby-Rack Configuration
@@ -190,18 +195,18 @@ as context init parameters in web.xml or as VM-wide system properties.
 
 - `rackup`: Rackup script for configuring how the Rack application is mounted.
   Required for Rack-based applications other than Rails. Can be omitted if a
-  *config.ru* is included in the application root.
+  `config.ru` is included in the application root.
 - `public.root`: Relative path to the location of your application's static
-  assets. Defaults to */*.
+  assets. Defaults to `*/*`.
 - `rails.root`: Root path to the location of the Rails application files.
-  Defaults to */WEB-INF*.
+  Defaults to `*/WEB-INF*`.
 - `rails.env`: Specify the Rails environment to run. Defaults to 'production'.
 - `rails.relative_url_append`: Specify a path to be appended to the
   `ActionController::Base.relative_url_root` after the context path. Useful
   for running a rails app from the same war as an existing app, under a
   sub-path of the main servlet context root.
 - `gem.path`: Relative path to the bundled gem repository. Defaults to
-  */WEB-INF/gems*.
+  `/WEB-INF/gems`.
 - `jruby.compat.version`: Set to "1.8" or "1.9" to make JRuby run a specific
   version of Ruby (same as the --1.8 / --1.9 command line flags).
 - `jruby.min.runtimes`: For non-threadsafe Rails applications using a runtime
@@ -263,17 +268,17 @@ as context init parameters in web.xml or as VM-wide system properties.
 
 There are often cases where you need to perform custom initialization of the
 Ruby environment before booting the application. You can create a file called
-*META-INF/init.rb* or *WEB-INF/init.rb* inside the war file for this purpose.
+`META-INF/init.rb` or `WEB-INF/init.rb` inside the war file for this purpose.
 These files, if found, will be evaluated before booting the Rack environment,
 allowing you to set environment variables, load scripts, etc.
 
 For plain Rack applications, JRuby-Rack also supports a magic comment to solve
 the "rackup" chicken-egg problem (you need Rack's builder loaded before loading
-the *config.ru*, yet you may want to setup the gem version from within the rackup
+the `config.ru`, yet you may want to setup the gem version from within the rackup
  file). As we ship with the Rack gem bundled, otherwise when executing the
-provided *config.ru* the bundled (latest) version of Rack will get loaded.
+provided `config.ru` the bundled (latest) version of Rack will get loaded.
 
-Use **rack.version** to specify the Rack gem version to be loaded before rackup :
+Use `rack.version` to specify the Rack gem version to be loaded before rackup :
 
 ```ruby
 # encoding: UTF-8
@@ -324,7 +329,7 @@ Build the .jar using Maven :
 ./mvnw install
 ```
 
-the generated jar should be located at **target/jruby-rack-*.jar**
+the generated jar should be located at `target/jruby-rack-*.jar`
 
 Alternatively use Rake, e.g. to build the gem (skipping specs) :