clean up API options table and add xrefs

1 files changed, 79 insertions, 104 deletions

diff --git a/docs/modules/api/pages/options.adoc b/docs/modules/api/pages/options.adoc
index fe4fc0ac..c0f30552 100644
--- a/docs/modules/api/pages/options.adoc
+++ b/docs/modules/api/pages/options.adoc
@@ -1,14 +1,14 @@
 = API Options
 
-[cols="15m,15,15,15,15"]
+[cols="~,~,30%,~"]
 |===
-|Name |Description |Default value |Allowed values |CLI equivalent
+|Name |Description |Default value |Allowed values
 
-|:attributes
-|Sets additional document attributes, which override equivalently-named attributes defined in the document unless the name or value ends with `@`.
-When using the Hash form, a `nil` value unsets the attribute and a `false` value soft unsets the attribute.
+|`:attributes`
+|Sets document attributes, which override equivalently-named attributes defined in the document unless soft set (`@`).
+When using the hash format, a `nil` value unsets the attribute and a `false` value soft unsets the attribute.
 |_not set_
-|Any number of #builtin-attributes,built-in# or user-defined attributes in one of the following formats:
+|xref:asciidoc:attributes:document-attributes.adoc[Document attributes] in the following formats:
 
 Hash: +
 `{'name'\=>'value'}` +
@@ -16,153 +16,128 @@ Array: +
 `['name=value']` +
 String: +
 `'name=value'`
-|`-a`, `--attributes`
 
-|:backend
-|Selects the converter to use (as registered with this keyword).
-|html5
-|html5, docbook5, manpage, or any backend registered through an active converter
-|`-b`, `--backend`
+|`:backend`
+|Selects the converter to use.
+|`html5`
+|`html5`, `docbook5`, `manpage`, or a backend registered through an active converter
 
-|:base_dir
+|`:base_dir`
 |Sets the base (aka working) directory containing the document and resources.
-|The directory of the source file, or the working directory if the source is read from a stream.
+|Directory of the source file, or the working directory if the source is read from a stream.
 |file path
-|`-B`, `--base-dir`
 
-|:catalog_assets
-|If true, tells the parser to capture images and links in the reference table.
+|`:catalog_assets`
+|If `true`, the parser captures images and links in the reference table.
 (Normally only IDs, footnotes and indexterms are included).
 The reference table is available via the `references` property on the `document` AST object.
 //NOTE: This is still a primitive and experimental feature.
 //It is intended for early adopters to address special use cases.
 _(Experimental)._
-|false
-|_boolean_
-|_n/a_
+|`false`
+|_Boolean_
 
-|:converter
-|Specifies a user-supplied `Asciidoctor::Converter` instance, used in place of the converter that is automatically resolved from the backend value.
+|`:converter`
+|Specifies a user-supplied `Asciidoctor::Converter` instance, used in place of the converter that is automatically resolved from the `backend` value.
 |_not set_
 |`Asciidoctor::Converter` instance
-|_n/a_
-_(Can be emulated using a combination of `-r` and `-b`)._
 
-|:doctype
+|`:doctype`
 |Sets the document type.
-|article
-|article, book, manpage, inline
-|`-d`, `--doctype`
+|`article`
+|`article`, `book`, `manpage`, `inline`
 
-|:eruby
+|`:eruby`
 |Specifies the eRuby implementation to use for executing the converter templates written in ERB.
-|erb
-|erb, erubis
-|`-e`, `--eruby`
+|`erb`
+|`erb`, `erubis`
 
-|:extensions
+|`:extensions`
 |A Ruby block that registers (and possibly defines) xref:extensions:register.adoc[Asciidoctor extensions] for this instance of the processor.
 |_not set_
 |A Ruby block that conforms to the Asciidoctor extensions API (the same code that would be passed to the `Extensions.register` method).
-|_n/a_
-_(Can be emulated using `-r`)._
 
-|:extensions_registry
+|`:extensions_registry`
 |Overrides the xref:extensions:register.adoc[extensions registry] instance.
 Instead of providing a Ruby block containing extensions to register, this option lets you replace the extension registry itself, giving you complete control over how extensions are registered for this processor.
 |_not set_
 |`Extensions::Registry` instance
-|_n/a_
 
-|:standalone
-|If true, generate a standalone output document (which includes the shell around the body content, such as the header and footer).
+|`:standalone`
+|If `true`, generates 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`
-
-|:mkdirs
-|If true, the processor will create the necessary output directories if they don't yet exist.
-|false
-|_boolean_
-|_n/a_
-_(Implicitly enabled)._
-
-|:parse
-|If true, the source is parsed eagerly (i.e., as soon as the source is passed to the `load` or `load_file` API).
-If false, parsing is deferred until the `parse` method is explicitly invoked.
-|true
-|_boolean_
-|_n/a_
-
-|:safe
+The default value for this option is opposite of the default value for the CLI.
+|_Varies_
+|_Boolean_
+
+|`:mkdirs`
+|If `true`, the processor creates the necessary output directories if they don't yet exist.
+|`false`
+|_Boolean_
+
+|`:parse`
+|If `true`, the source is parsed eagerly (i.e., as soon as the source is passed to the `load` or `load_file` API).
+If `false`, parsing is deferred until the `parse` method is explicitly invoked.
+|`true`
+|_Boolean_
+
+|`:safe`
 |Sets the xref:ROOT:safe-modes.adoc[safe mode].
-|:secure
-|:unsafe, :safe, :server, :secure
-|`-S`, `--safe-mode`
-
-|:sourcemap
-|Keeps track of the file and line number for each parsed block.
-(Useful for tooling applications where the association between the converted output and the source file is important).
-|false
-|_boolean_
-|_n/a_
-
-|:template_cache
-|If true, enables the built-in cache used by the template converter when reading the source of template files.
-Only relevant if the `:template_dirs` option is specified.
-|true
-|_boolean_
-|_n/a_
-
-|:template_dir
-|Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates.
-*Deprecated. Please use `:template_dirs` instead.*
+|`:secure`
+|`:unsafe`, `:safe`, `:server`, `:secure`
+
+|`:sourcemap`
+|Tracks the file and line number for each parsed block.
+Useful for tooling applications where the association between the converted output and the source file is important.
+|`false`
+|_Boolean_
+
+|`:template_cache`
+|Enables the built-in cache used by the template converter when reading the source of template files.
+Only relevant if `:template_dirs` is specified.
+|`true`
+|_Boolean_
+
+//|`:template_dir`
+//|Specifies a directory of Tilt-compatible templates to be used instead of the default built-in templates.
+//*Deprecated. Use `:template_dirs` instead.*
+//|_not set_
+//|file path
+
+|`:template_dirs`
+|Array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates.
 |_not set_
-|file path
-|`-T`, `--template-dir`
-
-|:template_dirs
-|An array of directories containing Tilt-compatible converter templates to be used instead of the default built-in templates.
-|_not set_
-|An array of file paths
-|`-T`, `--template-dir`
+|Array of file paths
 
-|:template_engine
+|`:template_engine`
 |Template engine to use for the custom converter templates.
 The gem with the same name as the engine will be loaded automatically.
 This name is also used to build the full path to the custom converter templates.
 |_auto_ +
 (Set based on the file extension of the custom converter templates found).
-|Template engine name (e.g., slim, haml, erb, etc.)
-|`-E`, `--template-engine`
+|Template engine name (e.g., `slim`, `haml`, `erb`, etc.)
 
-|:template_engine_options
+|`:template_engine_options`
 |Low-level options passed directly to the template engine.
 //(You can see an example in the Bespoke.js converter at https://github.com/asciidoctor/asciidoctor-bespoke/blob/v1.0.0.alpha.1/lib/asciidoctor-bespoke/converter.rb#L24-L28).
 |_not set_
-|A nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.
-|_n/a_
+|Nested Hash of options with the template engine name as the top-level key and the option name as the second-level key.
 
-|:timings
+|`:timings`
 |Capture time taken to read, parse, and convert document.
 *Internal use only.*
 |_not set_
 |`Asciidoctor::Timings` instance
-|`-t`, `--timings`
 
-|:to_file
-|The name of the output file to write, or true to use the default output file (`docname` + `outfilesuffix`).
+|`:to_file`
+|Name of the output file to write, or `true` to use the default output file (`docname` + `outfilesuffix`).
 |_not set_
-|true, file path
-|`-o`, `--out-file`
+|`true`, file path
 
-|:to_dir
+|`:to_dir`
 |Destination directory for output file(s), relative to `base_dir`.
-|The directory containing the source file, or the working directory if the source is read from a stream.
-|file path
-|`-D`, `--destination-dir`
+|Directory containing source file, or working directory if source is read from a stream.
+|File path
 |===