README.md in dotenv-rails-2.1.1 vs README.md in dotenv-rails-2.1.2

@@ -53,14 +53,24 @@
 ```
 
 As early as possible in your application bootstrap process, load `.env`:
 
 ```ruby
+require 'dotenv/load'
+
+# or
 require 'dotenv'
 Dotenv.load
 ```
 
+By default, `load` will look for a file called `.env` in the current working directory. Pass in multiple files and they will be loaded in order. The first value set for a variable will win.
+
+```
+require 'dotenv'
+Dotenv.load('file1.env', 'file2.env')
+```
+
 Alternatively, you can use the `dotenv` executable to launch your application:
 
 ```shell
 $ dotenv ./script.py
 ```
@@ -82,42 +92,61 @@
 ```shell
 S3_BUCKET=YOURS3BUCKET
 SECRET_KEY=YOURSECRETKEYGOESHERE
 ```
 
+Whenever your application loads, these variables will be available in `ENV`:
+
+```ruby
+config.fog_directory  = ENV['S3_BUCKET']
+```
+
+You may also add `export` in front of each line so you can `source` the file in bash:
+
+```shell
+export S3_BUCKET=YOURS3BUCKET
+export SECRET_KEY=YOURSECRETKEYGOESHERE
+```
+
+### Multi-line values
+
 If you need multiline variables, for example private keys, you can double quote strings and use the `\n` character for newlines:
 
 ```shell
 PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nHkVN9…\n-----END DSA PRIVATE KEY-----\n"
 ```
 
+### Command Substitution
+
 You need to add the output of a command in one of your variables? Simply add it with `$(your_command)`:
+
 ```shell
 DATABASE_URL="postgres://$(whoami)@localhost/my_database"
 ```
 
-You may also add `export` in front of each line so you can `source` the file in bash:
+### Variable Substitution
 
+You need to add the value of another variable in one of your variables? You can reference the variable with `${VAR}` or often just `$VAR` in unqoted or double-quoted values.
+
 ```shell
-export S3_BUCKET=YOURS3BUCKET
-export SECRET_KEY=YOURSECRETKEYGOESHERE
+DATABASE_URL="postgres://${USER}@localhost/my_database"
 ```
 
-Whenever your application loads, these variables will be available in `ENV`:
+If a value contains a `$` and it is not intended to be a variable, wrap it in single quotes.
 
-```ruby
-config.fog_directory  = ENV['S3_BUCKET']
+```shell
+PASSWORD='pas$word'
 ```
 
+### Comments
+
 Comments may be added to your file as such:
 
 ```shell
 # This is a comment
 SECRET_KEY=YOURSECRETKEYGOESHERE # comment
 SECRET_HASH="something-with-a-#-hash"
 ```
-
-Variable names may not contain the `#` symbol. Values can use the `#` if they are enclosed in quotes.
 
 ## Multiple Rails Environments
 
 dotenv was originally created to load configuration variables into `ENV` in *development*. There are typically better ways to manage configuration in production environments - such as `/etc/environment` managed by [Puppet](https://github.com/puppetlabs/puppet) or [Chef](https://github.com/chef/chef), `heroku config`, etc.