Document an example of the operation macro's equivalent Asciidoctor
Closes
@@ -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:
+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[snippets='curl-request,http-request,http-response']
+operation::index[]
----
-To include all of an operation's snippets, the `snippets` attribute can be omitted:
+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[]
+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:
|===
