rewrite the intro page for the API [skip ci]

1 files changed, 177 insertions, 26 deletions

diff --git a/docs/modules/api/pages/index.adoc b/docs/modules/api/pages/index.adoc
index 22ac5700..ab170389 100644
--- a/docs/modules/api/pages/index.adoc
+++ b/docs/modules/api/pages/index.adoc
@@ -1,45 +1,196 @@
 = Process AsciiDoc Using the API
 :url-api: https://www.rubydoc.info/gems/asciidoctor
-////
-API introduction for Asciidoctor
-included in the user-manual Quickstarts, Using the Ruby API
-////
 
-In addition to a CLI, Asciidoctor provides a {url-api}[Ruby API^] named `Asciidoctor`.
-This API is intended for integration with other Ruby software, such as Rails, GitHub, and GitLab, as well as other languages, such as Java (via xref:asciidoctorj::index.adoc[AsciidoctorJ]) and JavaScript (via xref:asciidoctor.js::index.adoc[Asciidoctor.js]).
+In addition to a CLI, Asciidoctor provides a {url-api}[Ruby API^] named `Asciidoctor` for parsing, analyzing, and converting AsciiDoc content.
+This API is intended for use in scripts, integration with other Ruby software, such as Rails, GitHub, and GitLab, and by other languages, such as Java (via xref:asciidoctorj::index.adoc[AsciidoctorJ]) and JavaScript (via xref:asciidoctor.js::index.adoc[Asciidoctor.js]).
 
-== Load and convert a document using the API
+This page covers how to get started with the Asciidoctor API, introduces its primary entry points, and explains where to get more information so you can use the API for more advanced use cases.
 
-To use the Asciidoctor API in your application, you first need to require the gem:
+== Use require to get started
 
-[source,ruby]
+To get started with the Asciidoctor API, you first need to xref:install:index.adoc[install the gem].
+The gem provides both the CLI and the Ruby API.
+In fact, the CLI uses the API to handle AsciiDoc conversion.
+
+Whereas with the CLI, you interact with Asciidoctor using the `asciidoctor` command, when using the API, you require the `asciidoctor` gem using Ruby's `require` function.
+From there, you interact with the `Asciidoctor` API.
+
+To start using the Asciidoctor API in your application or script, you first need to require the gem as show here:
+
+[,ruby]
+----
 require 'asciidoctor'
+----
+
+This one statement makes all of the {url-api}[public APIs in Asciidoctor^] available to your Ruby code.
+For example, we can check which version of Asciidoctor was required by Ruby using the following statement:
+
+[,ruby,subs=attributes+]
+----
+puts Asciidoctor::VERSION
+# => {release-version}
+----
+
+If the `require` statement fails, check to make sure that you have the gem installed (and available on the GEM_PATH).
+
+== API entrypoints
+
+The CLI is focused on converting AsciiDoc to various output formats.
+While the API can do that as well, it can do so much more.
+Instead of just converting AsciiDoc, the API allows you to load the AsciiDoc into a document model.
+From there, you can either convert the document model to an output format, or you can pause to analyze or modify its structure.
+
+There are four main entrypoints in the Asciidoctor API:
+
+`Asciidoctor.load`:: parses the AsciiDoc source (down to the block level) into an `Asciidoctor::Document` object
+`Asciidoctor.load_file`:: parses the contents of the AsciiDoc source file (down to the block level) into an `Asciidoctor::Document` object
+`Asciidoctor.convert`:: parses and converts the AsciiDoc source to the output format determined by the specified backend
+`Asciidoctor.convert_file`:: parses and converts the contents of the AsciiDoc source file to the output format determined by the specified backend
+
+If you're processing a file, you'd typically use a method that ends with `_file`.
+Otherwise, you'd use its complement, which accepts a String, an array of Strings, or an IO object.
 
-This one statement makes all of the {url-api}[public APIs in Asciidoctor^] available to your script or application.
-Now you can start processing AsciiDoc documents.
-The main entry points in the Asciidoctor API are the static methods on the `Asciidoctor` module to load or convert AsciiDoc documents, which we'll cover on this page.
+By default, the output of the convert methods follows the input.
+If you convert a String, the method will output a String.
+If you convert a file, the method will output to a file.
+However, these defaults can be changed using the options (e.g., `:to_file`).
 
-To parse a file into an `Asciidoctor::Document` object:
+When calling Asciidoctor using the API, you can access xref:options.adoc[additional options that control processing] which are not available when using the CLI.
+For example, you can pass in extensions, parse only the header, enable the sourcemap, or catalog assets.
 
-[source,ruby]
-doc = Asciidoctor.load_file 'my-sample.adoc'
+In addition to the main entrypoints, the API also provides a mechanism to register extensions via the `Asciidoctor::Extensions` API.
+To learn more about extensions, see xref:extensions:index.adoc[].
 
-You can get information about the document:
+== Load AsciiDoc using the API
 
-[source,ruby]
+When you load AsciiDoc using the API, you're telling Asciidoctor to parse the document (down to the block level) and return an `Asciidoctor::Document` object.
+This object contains the full block structure of the AsciiDoc document.
+
+CAUTION: Loading a document currently does not parse the inline content.
+That processing is deferred until the parsed document is converted.
+
+Let's assume we're working with the following AsciiDoc document:
+
+._document.adoc_
+[,asciidoc]
+----
+= Document Title
+
+The main content.
+----
+
+To parse this source file into an `Asciidoctor::Document` object, use the following API call:
+
+[,ruby]
+----
+doc = Asciidoctor.load_file 'document.adoc', safe: :safe
+----
+
+Using the object assigned to the `doc` variable, you can get information about the document, such as the document title.
+
+[,ruby]
+----
 puts doc.doctitle
-puts doc.attributes
+# => "Document Title"
+----
+
+You can also inspect all the document attributes:
+
+[,ruby]
+----
+pp doc.attributes
+----
+
+Going deeper, you can find blocks in the document, such as all the paragraph blocks, using the `find_by` method:
+
+[,ruby]
+----
+puts doc.find_by context: :paragraph
+# => #<Asciidoctor::Block@1001 {context: :paragraph, content_model: :simple, style: nil, lines: 1}>
+----
+
+If you're starting with a source String instead of a source file, you'd use the `load` method instead:
+
+[,ruby]
+----
+asciidoc = File.read 'document.adoc', mode: 'r:utf-8'
+doc = Asciidoctor.load asciidoc, safe: :safe
+----
+
+Once you have loaded the document, you can convert it by calling the convert method:
+
+[,ruby]
+-----
+doc.convert
+-----
+
+However, if you're only interested in converting the AsciiDoc source when using the API, then it's better to use a convert entrypoint.
+
+== Convert AsciiDoc using the API
+
+When you convert AsciiDoc using the API, you're telling Asciidoctor to parse and convert the document to the output format determined by the specified backend.
+If you don't specify a backend, like with the CLI, Asciidoctor will produce HTML.
+
+Let's again assume we're working with the following AsciiDoc document:
+
+._document.adoc_
+[,asciidoc]
+----
+= Document Title
+
+The main content.
+----
+
+To convert this source file to HTML5, use the following API call:
+
+[,ruby]
+----
+Asciidoctor.convert_file 'document.adoc', safe: :safe
+----
+
+The command will output HTML to the file [.path]_my-sample.html_ in the same directory.
+If you want Asciidoctor to output to a different file, you can specify it using the `:to_file` option:
+
+[,ruby]
+----
+Asciidoctor.convert_file 'document.adoc', safe: :safe, to_file: 'out.html'
+----
+
+You can convert the file to DocBook by setting the `:backend` option to `'docbook'`:
+
+[,ruby]
+----
+Asciidoctor.convert_file 'document.adoc', safe: :safe, backend: 'docbook'
+----
+
+In this case, Asciidoctor will output DocBook to the file [.path]_my-sample.xml_ in the same directory.
+As before, you can use the `:to_file` option to control the output file.
+
+If you're starting with a source String instead of a source file, you'd use the `convert` method instead:
 
-To convert a file containing AsciiDoc markup to HTML 5, use:
+[,ruby]
+----
+asciidoc = File.read 'document.adoc', mode: 'r:utf-8'
+html = Asciidoctor.convert asciidoc, safe: :safe
+----
 
-[source,ruby]
-Asciidoctor.convert_file 'my-sample.adoc'
+In this case, embedded HTML is returned.
+To instruct Asciidoctor to write standalone HTML to a file instead, the `:to_file` option is mandatory. 
 
-The command will output to the file [.path]_my-sample.html_ in the same directory.
+[,ruby]
+----
+asciidoc = File.read 'document.adoc', mode: 'r:utf-8'
+Asciidoctor.convert asciidoc, safe: :safe, to_file: 'out.html'
+----
 
-You can convert the file to DocBook 5.0 by setting the `:backend` option to `'docbook'`:
+That covers the basics of loading and converting AsciiDoc using the API.
 
-[source,ruby]
-Asciidoctor.convert_file 'my-sample.adoc', backend: 'docbook'
+== Next steps
 
-The command will output to the file [.path]_my-sample.xml_ in the same directory.
+* xref:convert-strings.adoc#embedded-output[Generating embedded vs standalone output]
+* xref:convert-strings.adoc#convert-inline-markup-only[Convert inline markup only]
+* xref:generate-html-doc[Generate an HTML TOC]
+* xref:load-templates.adoc[Load custom templates]
+* xref:extensions:index.adoc[Create extensions]
+* xref:options.adoc[API options]
+* {url-api}[Ruby API docs^]