Add a section to the docs that provides tips on working with Asciidoctor

Closes gh-75

docs/src/docs/asciidoc/getting-started.adoc

@@ -211,9 +211,6 @@ The `snippets` attribute specified in the <<getting-started-build-configuration,
 configuration>> can be used to reference the snippets output directory, for example:
 
 [source,adoc,indent=0]
-....
-[source,bash]
 ----
 \include::{snippets}/index/curl-request.adoc[]
 ----
-....

docs/src/docs/asciidoc/index.adoc

@@ -20,4 +20,5 @@ include::introduction.adoc[]
 include::getting-started.adoc[]
 include::documenting-your-api.adoc[]
 include::customizing-responses.adoc[]
-include::configuration.adoc[]
+include::configuration.adoc[]
+include::working-with-asciidoctor.adoc[]

docs/src/docs/asciidoc/working-with-asciidoctor.adoc

@@ -0,0 +1,75 @@
+[[working-with-asciidoctor]]
+== Working with Asciidoctor
+
+This section describes any aspects of working with Asciidoctor that are particularly
+relevant to Spring REST Docs.
+
+
+
+[[working-with-asciidoctor-resources]]
+=== Resources
+
+ * http://asciidoctor.org/docs/asciidoc-syntax-quick-reference[Syntax quick reference]
+ * http://asciidoctor.org/docs/user-manual[User manual]
+
+
+
+[[working-with-asciidoctor-including-snippets]]
+=== Including snippets
+
+The  http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#include-files[include
+macro] is used to include generated snippets in your documentation. The `snippets`
+attribute specified in the <<getting-started-build-configuration, build configuration>>
+can be used to reference the snippets output directory, for example:
+
+[source,adoc,indent=0]
+----
+\include::{snippets}/index/curl-request.adoc[]
+----
+
+
+
+[[working-with-asciidoctor-customizing-tables]]
+=== Customizing tables
+
+Many of the snippets contain a table in its default configuration. The appearance of the
+table can be customized by providing some additional configuration when the snippet is
+included.
+
+
+
+[[working-with-asciidoctor-customizing-tables-formatting-columns]]
+==== Formatting columns
+
+Asciidoctor has rich support for http://asciidoctor.org/docs/user-manual/#cols-format
+[formatting a table's columns]. For example, the widths of a table's columns can be
+specified using the `cols` attribute:
+
+[source,adoc,indent=0]
+----
+[cols=1,3] <1>
+\include::{snippets}index/links.adoc[]
+----
+<1> The table's width will be split across its two columns with the second column being
+three times as wide as the first.
+
+
+
+[[working-with-asciidoctor-customizing-tables-title]]
+==== Configuring the title
+
+The title of a table can be specified using a line prefixed by a `.`:
+
+[source,adoc,indent=0]
+----
+.Links <1>
+\include::{snippets}index/links.adoc[]
+----
+<1> The table's title will be `Links`.
+
+
+
+==== Further reading
+
+Refer to the http://asciidoctor.org/docs/user-manual/#tables[Tables section of
+the Asciidoctor user manual] for more information about customizing tables.