Allow asciidoctor to read from uri, update README

- Allow asciidoctor to read from URI (contributing section)
- Add 'building documentation' section
- Add newly-updated README
- Small spelling fixes

README.adoc

@@ -27,6 +27,27 @@ Services](https://run.pivotal.io)).
 
 > NOTE: if you are looking for a way to bind to services then this is the wrong library. Check out the [Spring Cloud Connectors](https://github.com/spring-cloud/spring-cloud-connectors) instead.
 
+= Building documentation
+
+`./mvnw install -P docs -DskipTests=true --settings .settings.xml`
+
+If there is an ruby error like
+
+--------------------------------------------------------------
+LoadError: no such file to load -- asciidoctor
+--------------------------------------------------------------
+
+then the user must install the _asciidoctor_ gem and set the environment
+variable `GEM_HOME`to the ruby gem folder. For example:
+
+-------------------------------------------------------------
+  # Get gem info
+  gem environment
+
+  export GEM_HOME=<PATH FOR GEM ENVIRONMENT>
+
+-------------------------------------------------------------
+
 == Contributing
 
 link:https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]

docs/src/main/asciidoc/README.adoc

@@ -6,6 +6,27 @@ include::intro.adoc[]
 
 > NOTE: if you are looking for a way to bind to services then this is the wrong library. Check out the [Spring Cloud Connectors](https://github.com/spring-cloud/spring-cloud-connectors) instead.
 
+= Building documentation
+
+`./mvnw install -P docs -DskipTests=true --settings .settings.xml`
+
+If there is an ruby error like
+
+--------------------------------------------------------------
+LoadError: no such file to load -- asciidoctor
+--------------------------------------------------------------
+
+then the user must install the _asciidoctor_ gem and set the environment
+variable `GEM_HOME`to the ruby gem folder. For example:
+
+-------------------------------------------------------------
+  # Get gem info
+  gem environment
+
+  export GEM_HOME=<PATH FOR GEM ENVIRONMENT>
+
+-------------------------------------------------------------
+
 == Contributing
 
 include::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/contributing.adoc[]

docs/src/main/asciidoc/quickstart.adoc

@@ -26,5 +26,5 @@ $ spring jar app.jar app.groovy
 $ cf push -p app.jar
 ----
 
-it will show it's app name in the home page.
+It will show its app name in the home page.
 

docs/src/main/ruby/generate_readme.sh

@@ -18,7 +18,7 @@ file = ARGV[0] if ARGV.length>0
 
 srcDir = File.dirname(file)
 out = "// Do not edit this file (e.g. go instead to docs/src/main/asciidoc)\n\n"
-doc = Asciidoctor.load_file file, safe: :safe, parse: false
+doc = Asciidoctor.load_file file, safe: :safe, parse: false, attributes: 'allow-uri-read'
 out << doc.reader.read
 
 unless options[:to_file]