From baa8e6bb904a88097cf14f12f56e9bcdf8949ce1 Mon Sep 17 00:00:00 2001
From: Andy Wilkinson <awilkinson@pivotal.io>
Date: Wed, 28 Mar 2018 10:10:10 +0100
Subject: [PATCH] Document an example of the operation macro's equivalent
 Asciidoctor

Closes gh-470
---
 .../asciidoc/working-with-asciidoctor.adoc    | 48 ++++++++++++++-----
 1 file changed, 35 insertions(+), 13 deletions(-)

diff --git a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc
index 2a0cf6bd..de36f81c 100644
--- a/docs/src/docs/asciidoc/working-with-asciidoctor.adoc
+++ b/docs/src/docs/asciidoc/working-with-asciidoctor.adoc
@@ -30,30 +30,52 @@ use version 1.5.6 of the `org.asciidoctor.convert` plugin. It contains a
 https://github.com/asciidoctor/asciidoctor-gradle-plugin/issues/222[regression] that
 prevents extensions from working reliably.
 
-The target of the macro is the name of the operation. The `snippets` attribute can be
-used to select the snippets that should be included using a comma-separated list.
-Each entry in the list should be the name of a snippet file, minus the `.adoc` suffix,
-to include. For example, to include the curl, HTTP request and HTTP response snippets
-for the index operation:
-
-[source,indent=0]
-----
-operation::index[snippets='curl-request,http-request,http-response']
-----
-
-To include all of an operation's snippets, the `snippets` attribute can be omitted:
+The target of the macro is the name of the operation. In its simplest form, the macro
+can be used to include all of the snippets for an operation, as shown in the following
+example:
 
 [source,indent=0]
 ----
 operation::index[]
 ----
 
+The operation macro also supports a `snippets` attribute. The `snippets` attribute can be
+used to select the snippets that should be included. The attribute's value is a
+comma-separated list. Each entry in the list should be the name of a snippet file, minus
+the `.adoc` suffix, to include. For example, only the curl, HTTP request and HTTP response
+snippets can be included as shown in the following example:
+
+[source,indent=0]
+----
+operation::index[snippets='curl-request,http-request,http-response']
+----
+
+This is the equivalent of the following:
+
+[source,adoc,indent=0]
+----
+[[example_curl_request]]
+== Curl request
+
+\include::{snippets}/index/curl-request.adoc[]
+
+[[example_http_request]]
+== HTTP request
+
+\include::{snippets}/index/http-request.adoc[]
+
+[[example_http_response]]
+== HTTP response
+
+\include::{snippets}/index/http-response.adoc[]
+
+----
 
 
 [[working-with-asciidoctor-including-snippets-operation-titles]]
 ===== Section titles
 
-For each snippet that's including using `operation` a section with a title will be
+For each snippet that's including using `operation`, a section with a title will be
 created. Default titles are provided for the built-in snippets:
 
 |===