add my-document source and image references, update associated content

5 files changed, 86 insertions, 74 deletions

diff --git a/docs/modules/html-backend/images/no-stylesheet.png b/docs/modules/html-backend/images/no-stylesheet.png
index 77e880ad..ffe779b8 100644
--- a/docs/modules/html-backend/images/no-stylesheet.png
+++ b/docs/modules/html-backend/images/no-stylesheet.png
diff --git a/docs/modules/html-backend/pages/custom-stylesheet.adoc b/docs/modules/html-backend/pages/custom-stylesheet.adoc
index 578681f4..18591039 100644
--- a/docs/modules/html-backend/pages/custom-stylesheet.adoc
+++ b/docs/modules/html-backend/pages/custom-stylesheet.adoc
@@ -30,29 +30,26 @@ Now let's use the `stylesheet` attribute to apply it.
 The `stylesheet` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
+.stylesheet attribute set in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :stylesheet: my-stylesheet.css
-
-In my world, we don't have to worry about mutant, script-injecting warlocks.
-No.
-We have something far worse.
-We're plagued by Wolpertingers.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also set `stylesheet` using the API or CLI (shown here):
 
- $ asciidoctor -a stylesheet=my-stylesheet.css document.adoc
+ $ asciidoctor -a stylesheet=my-stylesheet.css my-document.adoc
 
-When you view the generated HTML file [.path]_document.html_ in your browser, you'll see that all the text is red.
+When you view the generated HTML file [.path]_my-document.html_ in your browser, you'll see that all the text is red.
 
 TIP: If you want to create a custom stylesheet by extending the default stylesheet, see xref:default-stylesheet.adoc#customize-extend[Extend the default stylesheet].
 
 As with the default stylesheet, you can set the `linkcss` document attribute and Asciidoctor will link to your stylesheet instead.
 (Note that it doesn't copy it in this case since it's already in the same folder as the output file).
 
- $ asciidoctor -a stylesheet=my-stylesheet.css -a linkcss document.adoc
+ $ asciidoctor -a stylesheet=my-stylesheet.css -a linkcss my-document.adoc
 
 You may not want to keep your stylesheet in the same directory as your AsciiDoc documents.
 Let's see how to tell Asciidoctor to look for it elsewhere.
@@ -77,27 +74,24 @@ Now we need to tell Asciidoctor where it's located using `stylesdir`.
 The `stylesdir` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
+.stylesdir attribute set in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :stylesheet: my-stylesheet.css
 :stylesdir: my-styles
-
-In my world, we don't have to worry about mutant, script-injecting warlocks.
-No.
-We have something far worse.
-We're plagued by Wolpertingers.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also set `stylesdir` using the API or CLI (shown here):
 
- $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css document.adoc
+ $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css my-document.adoc
 
 Asciidoctor now looks for the stylesheet file [.path]_my-styles/my-stylesheet.css_ relative to the AsciiDoc document and embeds it into the HTML.
 
 You can achieve the same result by including the directory in the value of the `stylesheet` attribute:
 
- $ asciidoctor -a stylesheet=my-styles/my-stylesheet.css document.adoc
+ $ asciidoctor -a stylesheet=my-styles/my-stylesheet.css my-document.adoc
 
 If you set the value of `stylesdir` to an absolute directory, then Asciidoctor would still locate the stylesheet and embed it into the HTML.
 But this can create problems if you've configured the converter to link to the stylesheet instead.
@@ -115,7 +109,7 @@ First, it's important to understand that Asciidoctor mirrors the `stylesdir` pat
 Let's use the previous example to demonstrate.
 If you invoke Asciidoctor as follows:
 
- $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css -a linkcss document.adoc
+ $ asciidoctor -a stylesdir=my-styles -a stylesheet=my-stylesheet.css -a linkcss my-document.adoc
 
 Then when you inspect the HTML, you will see:
 
@@ -131,9 +125,9 @@ There are certain situations where this isn't going to work (at least not when p
 Let's consider one such case.
 We'll specify the location of `stylesdir` as an absolute path and generate the output file into a separate output directory.
 
- $ asciidoctor -a stylesdir=`pwd`/my-styles -a stylesheet=my-stylesheet.css -a linkcss -D public document.adoc
+ $ asciidoctor -a stylesdir=`pwd`/my-styles -a stylesheet=my-stylesheet.css -a linkcss -D public my-document.adoc
 
-Asciidoctor generates the HTML file into the [.path]_public_ folder, but it _does not_ copy the stylesheet.
+Asciidoctor generates the HTML file into the [.path]_public_ folder, but it does not copy the stylesheet.
 Furthermore, it uses an absolute path in the link to the stylesheet:
 
 [source,html]
@@ -165,7 +159,7 @@ That means we can use `stylesdir` and `stylesheet` to assemble the path relative
 Let's revisit the broken scenario from the previous section and use `copycss` to reconcile the problem:
 
  $ asciidoctor -a stylesdir=css -a stylesheet=default.css \
- -a copycss=`pwd`/my-styles/my-stylesheet.css -a linkcss -D public document.adoc
+ -a copycss=`pwd`/my-styles/my-stylesheet.css -a linkcss -D public my-document.adoc
 
 Asciidoctor copies the stylesheet from the absolute path specified by the `copycss` attribute to the path [.path]_public/css/default.css_ and links to it using the path [.path]_css/default.css_.
 Notice that we even changed the name of the folder and stylesheet file in the output.
diff --git a/docs/modules/html-backend/pages/index.adoc b/docs/modules/html-backend/pages/index.adoc
index 2e556ed4..b9d89a91 100644
--- a/docs/modules/html-backend/pages/index.adoc
+++ b/docs/modules/html-backend/pages/index.adoc
@@ -11,44 +11,52 @@ Asciidoctor's default output format is HTML.
 
 In this section, we'll create a sample document, then process and convert it with Asciidoctor's built-in HTML converter.
 
-. Create an AsciiDoc file like the one below
-. Save the file as [.path]_my-sample.adoc_
+=== Create and save an AsciiDoc document
 
-[source,asciidoc]
+. To follow along with the steps below, use your own AsciiDoc file or copy the contents of <<ex-my-doc>> into a new plaintext file.
++
+.my-document.adoc
+[source#ex-my-doc,asciidoc]
 ----
-include::example$mysample.adoc[]
+include::example$my-document.adoc[tags=title;body]
 ----
 
-To convert [.path]_my-sample.adoc_ to HTML from the command line:
+. Make sure to save the file with the _.adoc_ file extension.
 
-. Open a console
-. Switch to the directory that contains the [.path]_my-sample.adoc_ document
-. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document you want to convert
+=== Convert an AsciiDoc document to HTML
 
-//^
+To convert [.path]_my-document.adoc_ to HTML from the command line:
 
- $ asciidoctor my-sample.adoc
+. Open a terminal.
+. Switch to the directory that contains the [.path]_my-document.adoc_ document
+. Call the Asciidoctor processor with the `asciidoctor` command, followed by the name of the document.
++
+--
+ $ asciidoctor my-document.adoc
 
 Remember, Asciidoctor's default converter is html5, so it isn't necessary to specify it with the `-b` command.
+--
 
-You won't see any messages printed to the console.
-If you type `ls` or view the directory in a file manager, there is a new file named [.path]_my-sample.html_.
-
+. You won't see any messages printed to the console.
+Type `ls` to view the files in the directory or navigate to the directory in a file manager.
+You should see a new file named [.path]_my-document.html_.
++
+--
  $ ls
- my-sample.adoc  my-sample.html
+ my-document.adoc  my-document.html
 
 Asciidoctor derives the name of the output document from the name of the input document.
+--
 
-Open [.path]_my-sample.html_ in your web browser.
+. Open [.path]_my-document.html_ in your web browser.
 Your document should look like the image below.
++
+--
+image::my-document.png[]
 
-====
-#fix ex#
-//image::mysample.png[]
-====
-
-The document's text, titles, and link is styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
-As a result, you could save [.path]_my-sample.html_ to any computer and it will look the same.
+The document's text, titles, and link are styled by the default Asciidoctor stylesheet, which is embedded in the HTML output.
+As a result, you could save [.path]_my-document.html_ to any computer and it will look the same.
+--
 
 [#xhtml]
 == Generate XHTML
@@ -59,7 +67,7 @@ To use the XHTML converter, assign `xhtml` or `xhtml5` to the `backend` option.
 .Produce XHTML using the xhtml5 backend option
 [source,console]
 ----
-asciidoctor -b xhtml5 document.adoc
+$ asciidoctor -b xhtml5 my-document.adoc
 ----
 
 To produce XHTML instead of HTML when using converter templates, set the `htmlsyntax` attribute to `xml` in addition to the backend option:
@@ -67,7 +75,7 @@ To produce XHTML instead of HTML when using converter templates, set the `htmlsy
 .Produce XHTML using custom templates
 [source,console]
 ----
-asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml document.adoc
+$ asciidoctor -T /path/to/templates -b slides -a htmlsyntax=xml my-document.adoc
 ----
 
 .Black Box Decoded: XHTML and htmlsyntax
diff --git a/docs/modules/html-backend/pages/manage-images.adoc b/docs/modules/html-backend/pages/manage-images.adoc
index 38b69aae..94323a93 100644
--- a/docs/modules/html-backend/pages/manage-images.adoc
+++ b/docs/modules/html-backend/pages/manage-images.adoc
@@ -3,22 +3,31 @@
 Images are not embedded in the HTML output by default.
 If you have image references in your document, you'll have to save the image files in the same directory as your converted document.
 
-As an alternative, you can embed the images directly into the document by setting the `data-uri` document attribute.
+== Embed images with the data-uri attribute
 
- $ asciidoctor -a data-uri my-sample.adoc
+As an alternative, you can embed the images directly into the document by setting the `data-uri` document attribute.
 
+.data-uri attribute set in document header
 [source,asciidoc]
 ----
-include::example$mysample-data-uri.adoc[]
+include::example$my-document.adoc[tag=title]
+:imagesdir: my-images
+:data-uri:
+include::example$my-document.adoc[tags=body;image]
 ----
 
-====
-#fix ex#
-//image::mysample-data-uri.png[]
-====
+You can also set `data-uri` using the API or CLI (shown here):
+
+ $ asciidoctor -a data-uri my-document.adoc
+
+When you view the HTML file in your browser, you should see the image displayed in the page.
+
+image::my-document-with-data-uri.png[]
+
+== allow-uri-read attribute
 
 If the target of one or more images in the document is a URI, you must also set the `allow-uri-read` attribute securely and run Asciidoctor in `SECURE` mode or less.
 
- $ asciidoctor -a data-uri -a allow-uri-read my-sample.adoc
+ $ asciidoctor -a data-uri -a allow-uri-read my-document.adoc
 
 The same is true when converting the document to PDF using Asciidoctor PDF, even if the `allow-uri-read` attribute is not set (since the behavior is implied).
diff --git a/docs/modules/html-backend/pages/stylesheet-modes.adoc b/docs/modules/html-backend/pages/stylesheet-modes.adoc
index 8b2fdd90..5379ed38 100644
--- a/docs/modules/html-backend/pages/stylesheet-modes.adoc
+++ b/docs/modules/html-backend/pages/stylesheet-modes.adoc
@@ -32,23 +32,21 @@ If the `linkcss` document attribute is set, the converter will take this hint to
 The `linkcss` document attribute must be set by the end of the header to be effective.
 One way to do that is to set the attribute in the document header:
 
+.linkcss attribute set in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :linkcss:
-
-In my world, we don't have to worry about mutant, script-injecting warlocks.
-No.
-We have something far worse.
-We're plagued by Wolpertingers.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also set `linkcss` using the API or CLI (shown here):
 
- $ asciidoctor -a linkcss document.adoc
+ $ asciidoctor -a linkcss my-document.adoc
 
-In either case, if you inspect the `<head>` tag in the output file [.path]_document.html_, you'll see that the HTML links to the stylesheet.
+In either case, if you inspect the `<head>` tag in the output file [.path]_my-document.html_, you'll see that the HTML links to the stylesheet.
 
+.my-document.html
 [source,html]
 ----
 <link rel="stylesheet" href="./asciidoctor.css">
@@ -69,7 +67,7 @@ When using the default stylesheet, Asciidoctor writes the CSS to the file [.path
 If you specify a custom stylesheet, Asciidoctor will copy that file instead, retaining the name of the file.
 This utility works even if you specify an xref:cli:output-file.adoc[output file in a different directory] from the source file.
 
-.A shared responsiblity
+.A shared responsibility
 ****
 While the converter handles the task of embedding or linking to the stylesheet file, it's the processor itself (not the converter) that handles copying the stylesheet.
 ****
@@ -78,9 +76,15 @@ If the safe mode is secure, Asciidoctor will not copy the stylesheet file and, t
 
 Let's revisit the previous example:
 
- $ asciidoctor -a linkcss document.adoc
+ $ asciidoctor -a linkcss my-document.adoc
+
+After running this command, the stylesheet file [.path]_asciidoctor.css_ is copied to the same directory as the generated HTML file [.path]_my-document.html_.
+Type `ls` to view the files in the directory.
+You should see a file named [.path]_asciidoctor.css_.
+
+ $ ls
+ asciidoctor.css  my-document.adoc  my-document.html
 
-After running this command, you should see the stylesheet file [.path]_asciidoctor.css_ adjacent to the HTML file [.path]_document.html_.
 When you view the HTML file in your browser, you should observe that the default stylesheet is applied.
 
 === To copy or not to copy
@@ -93,21 +97,18 @@ To prevent Asciidoctor from copying the stylesheet independent of safe mode, uns
 The `copycss` document attribute must be unset by the end of the header to be effective.
 One way to do that is to unset the attribute in the document header:
 
+.copycss attribute unset in document header
 [source,asciidoc]
 ----
-= My First Experience with the Dangers of Documentation
+include::example$my-document.adoc[tag=title]
 :linkcss:
 :!copycss:
-
-In my world, we don't have to worry about mutant, script-injecting warlocks.
-No.
-We have something far worse.
-We're plagued by Wolpertingers.
+include::example$my-document.adoc[tag=body]
 ----
 
 You can also unset `copycss` using the API or CLI (shown here):
 
- $ asciidoctor -a linkcss -a copycss! document.adoc
+ $ asciidoctor -a linkcss -a copycss! my-document.adoc
 
 In either case, if you inspect the output directory, you will see that the stylesheet file [.path]_asciidoctor.css_ is missing (unless it was already there).
 
@@ -117,15 +118,15 @@ We'll see the `copycss` attribute come up again on the xref:custom-stylesheet.ad
 == Disable the stylesheet
 
 The stylesheet is effectively disabled when generating embedded HTML, since the embedded HTML does not include the `<head>` tag.
-If you don't want the converter to include a stylesheet in the standalone HTML, unset the `stylesheet` document attribute:
+If you don't want the converter to include a stylesheet in the standalone HTML, unset the `stylesheet` attribute using the CLI.
 
- $ asciidoctor -a stylesheet! document.adoc
+ $ asciidoctor -a stylesheet! my-document.adoc
 
 The reason you have to unset the `stylesheet` attribute is because it is set by default (to an empty value).
 When the `stylesheet` attribute is set, but empty, the HTML converter uses the default stylesheet.
 By unsetting this attribute, we're telling the converter not to use a stylesheet at all.
 
-When you view the generated HTML file, [.path]_document.html_, you'll see bare HTML without any styles applied, as shown here:
+When you view the generated HTML file, [.path]_my-document.html_, you'll see bare HTML without any styles applied, as shown here:
 
 image::no-stylesheet.png[]