add :standalone option to Ruby API options; list :header_footer as deprecated alias

5 files changed, 19 insertions, 16 deletions

diff --git a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
index 4d28d210..1d18c502 100644
--- a/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
+++ b/docs/modules/ROOT/pages/attributes-and-safe-modes.adoc
@@ -36,11 +36,11 @@ Example:
 To be secure by default, the allow-uri-read attribute must be set in the API or CLI (not document) for this feature to be enabled. It's also completely disabled if the safe mode is SECURE or greater.
 Since this is a potentially dangerous feature, it’s disabled if the safe mode is SECURE or greater. Assuming the safe mode is less than SECURE, you must also set the allow-uri-read attribute to permit Asciidoctor to read content from a URI.
 
-I decided the following defaults for the header_footer option make the most sense:
+I decided the following defaults for the standalone option make the most sense:
 
 true if using the cli (use -s to disable, consistent with asciidoc)
 false if using the API, unless converting directly to a file, in which case true is the default
 The basic logic is that if you are writing to a file, you probably want to create a standalone document. If you are converting to a string, then you probably want an embedded document. Of course, you can always set it explicitly, this is just a default setting.
 
-The reason I think the header_footer default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now.
+The reason I think the standalone default is important is because we don't want people switching from Markdown to AsciiDoc and be totally taken by surprise when they start getting a full HTML document. On the other hand, if you are converting to a file (or using the cli), then it makes a lot of sense to write a standalone document. To me, it just feels natural now.
 ////
diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc
index 1f4a102a..6eec4faf 100644
--- a/docs/modules/api/pages/convert-strings.adoc
+++ b/docs/modules/api/pages/convert-strings.adoc
@@ -45,26 +45,26 @@ Here's what's included in an embedded document:
 == Standalone output
 
 You can still generate a standalone document when converting a string.
-To convert from an AsciiDoc string to a standalone output document, you need to explicitly set the `header_footer` option to `true`.
+To convert from an AsciiDoc string to a standalone output document, you need to explicitly set the `standalone` option to `true`.
 
 [source,ruby]
 ----
-puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true
+puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true
 ----
 
 Now you will see a full HTML file.
 
-When the input or output is a file, the `header_footer` option is enabled by default.
+When the input or output is a file, the `standalone` option is enabled by default.
 
 [source,ruby]
 ----
 Asciidoctor.convert '*This* is Asciidoctor.', to_file: 'out.html'
 ----
 
-If you want to generate embedded output when starting with a file, set the `header_footer` option to `false`.
+If you want to generate embedded output when starting with a file, set the `standalone` option to `false`.
 However, most of the time you'll want to generate a standalone document when converting a file (which is why it's default).
 
-When converting a string, the TOC is only included by default when using the `header_footer` option as shown above (whether it's enabled implicitly or explicitly).
+When converting a string, the TOC is only included by default when using the `standalone` option as shown above (whether it's enabled implicitly or explicitly).
 However, you can force it to be included without the header and footer by setting the `toc` attribute with a value of `macro` and using the `toc::[]` macro in the string itself.
 
 == Convert inline markup only
@@ -81,9 +81,9 @@ In this mode, Asciidoctor will only process the first block (e.g., paragraph) in
 == Convert to DocBook
 
 You can produce DocBook 5.0 by setting the `backend` option to `'docbook'`.
-Since embeddable DocBook isn't that useful, we also enable the standalone document (i.e., header and footer) by setting the `header_footer` option to `true`.
+Since embeddable DocBook isn't that useful, we also enable the standalone document (i.e., header and footer) by setting the `standalone` option to `true`.
 
 [source,ruby]
 ----
-puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true, backend: 'docbook'
+puts Asciidoctor.convert '*This* is Asciidoctor.', standalone: true, backend: 'docbook'
 ----
diff --git a/docs/modules/api/pages/load-templates.adoc b/docs/modules/api/pages/load-templates.adoc
index 487ecd57..2f9a16f1 100644
--- a/docs/modules/api/pages/load-templates.adoc
+++ b/docs/modules/api/pages/load-templates.adoc
@@ -8,8 +8,8 @@ It will fallback to its default templates for everything else.
 
 [source,ruby]
 ----
-puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true,
-  :template_dir => 'templates'
+puts Asciidoctor.convert '*This* is Asciidoctor.',
+  standalone: true, template_dir: 'templates'
 ----
 
 The Document and Section templates should begin with `document` and `section`, respectively.
diff --git a/docs/modules/api/pages/options.adoc b/docs/modules/api/pages/options.adoc
index 5a498567..fe4fc0ac 100644
--- a/docs/modules/api/pages/options.adoc
+++ b/docs/modules/api/pages/options.adoc
@@ -74,10 +74,13 @@ Instead of providing a Ruby block containing extensions to register, this option
 |`Extensions::Registry` instance
 |_n/a_
 
-|:header_footer
-|If true, add the document header and footer (i.e., framing) around the body content in the output.
-NOTE: The default value for this option is opposite of the default value for the CLI.
-|false
+|:standalone
+|If true, generate a standalone output document (which includes the shell around the body content, such as the header and footer).
+When converting to a file, the default value is `true`.
+Otherwise, the default value is `false`.
+The deprecated alias for this option is `:header_footer`.
+Note that the default value for this option is opposite of the default value for the CLI.
+|_contingent_
 |_boolean_
 |`-s`, `--no-header-footer`
 
diff --git a/docs/modules/html-backend/pages/favicon.adoc b/docs/modules/html-backend/pages/favicon.adoc
index 34a8f15d..a6400aff 100644
--- a/docs/modules/html-backend/pages/favicon.adoc
+++ b/docs/modules/html-backend/pages/favicon.adoc
@@ -1,6 +1,6 @@
 = Add a Favicon
 
-When using Asciidoctor to generate a standalone HTML document (i.e., the `header_footer` option is `true`), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header.
+When using Asciidoctor to generate a standalone HTML document (i.e., the `standalone` option is `true`), you can instruct the processor to include a link to a favicon by setting the favicon attribute in the document header.
 
 [source,asciidoc]
 ----