From c3c7ddbda681cc8f44832b0549bb623d3eace748 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Wed, 18 Nov 2020 15:53:10 -0700 Subject: rearchitect modules and filenames and drop asciidoctor folder under docs --- docs/modules/api/nav.adoc | 6 + docs/modules/api/pages/convert-strings.adoc | 89 ++++++++++++++ docs/modules/api/pages/generate-html-toc.adoc | 33 ++++++ docs/modules/api/pages/index.adoc | 50 ++++++++ docs/modules/api/pages/load-templates.adoc | 24 ++++ docs/modules/api/pages/options.adoc | 165 ++++++++++++++++++++++++++ docs/modules/api/pages/set-safe-mode.adoc | 18 +++ 7 files changed, 385 insertions(+) create mode 100644 docs/modules/api/nav.adoc create mode 100644 docs/modules/api/pages/convert-strings.adoc create mode 100644 docs/modules/api/pages/generate-html-toc.adoc create mode 100644 docs/modules/api/pages/index.adoc create mode 100644 docs/modules/api/pages/load-templates.adoc create mode 100644 docs/modules/api/pages/options.adoc create mode 100644 docs/modules/api/pages/set-safe-mode.adoc (limited to 'docs/modules/api') diff --git a/docs/modules/api/nav.adoc b/docs/modules/api/nav.adoc new file mode 100644 index 00000000..25a3a937 --- /dev/null +++ b/docs/modules/api/nav.adoc @@ -0,0 +1,6 @@ +* xref:index.adoc[] +** xref:convert-strings.adoc[] +** xref:generate-html-toc.adoc[] +** xref:load-templates.adoc[] +** xref:set-safe-mode.adoc[] +** xref:options.adoc[] diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc new file mode 100644 index 00000000..1f4a102a --- /dev/null +++ b/docs/modules/api/pages/convert-strings.adoc @@ -0,0 +1,89 @@ += Load and Convert Strings Using the API +:navtitle: Load and Convert Strings + +To parse an AsciiDoc-formatted string into a document object model, use: + +[source,ruby] +---- +doc = Asciidoctor.load '*This* is Asciidoctor.' +---- + +To convert the AsciiDoc-formatted string directly to HTML, use: + +[source,ruby] +---- +puts Asciidoctor.convert '*This* is Asciidoctor.' +---- + +Here's the output you will see: + +[source,html] +---- +
+

This is Asciidoctor.

+
+---- + +When converting a string, Asciidoctor does not output a standalone document by default. +Instead, it generates embeddable output. +Let's learn why that is and how to control it. + +== Embedded output + +When you pass a string to `Asciidoctor.convert` to convert it to a backend format, such as HTML, this method only returns the converted content for those blocks. +It does not include the frame around that content (i.e., the header and footer) that is needed to make a standalone document. +Instead, it makes an _embedded_ document. +This default was chosen to make Asciidoctor consistent with other lightweight markup processors like Markdown. + +Here's what's included in an embedded document: + +* The document title, but only if the `showtitle` attribute is set (no attribution and revision information) +* The table of contents if the `toc` attribute is enabled (and not macro or preamble) +* The converted document body +* The footnotes unless the `nofootnotes` attribute is set + +== 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`. + +[source,ruby] +---- +puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: 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. + +[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`. +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). +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 + +If you only want the inline markup to be returned, set the `:doctype` option to `'inline'`: + +[source,ruby] +---- +puts Asciidoctor.convert '*This* is Asciidoctor.', :doctype => 'inline' +---- + +In this mode, Asciidoctor will only process the first block (e.g., paragraph) in the document and ignore the rest. + +== 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`. + +[source,ruby] +---- +puts Asciidoctor.convert '*This* is Asciidoctor.', header_footer: true, backend: 'docbook' +---- diff --git a/docs/modules/api/pages/generate-html-toc.adoc b/docs/modules/api/pages/generate-html-toc.adoc new file mode 100644 index 00000000..c53a538b --- /dev/null +++ b/docs/modules/api/pages/generate-html-toc.adoc @@ -0,0 +1,33 @@ += Generate an HTML TOC + +Asciidoctor's HTML 5 converter has built-in support for generating a TOC. +This TOC generator can also be used as a general purpose API. +This logic is available via the `outline` method on the HTML5 converter. + +The `outline` method excepts a Document object and an optional Hash of options, and returns an HTML string. +It can be resolved and invoked from anywhere using the following: + +[source,ruby] +---- +html_toc = (Asciidoctor::Converter.for 'html5').outline document +---- + +The method can also be executed from inside a converter template (e.g., Slim, Haml, or ERB). +When using a composite converter, this call will be run through the converter chain. + +[source,ruby] +---- += converter.convert document, 'outline' +---- + +The method is also available through the Document API: + +[source,ruby] +---- +html_doc = document.converter.convert document, 'outline' +---- + +The `outline` method accepts the following options: + +sectnumlevels:: the number of section levels to number (defaults to the value of the `sectnumlevels` attribute. +toclevels:: the depth of the toc (defaults to the value of the `toclevels` attribute) diff --git a/docs/modules/api/pages/index.adoc b/docs/modules/api/pages/index.adoc new file mode 100644 index 00000000..5c909faa --- /dev/null +++ b/docs/modules/api/pages/index.adoc @@ -0,0 +1,50 @@ += 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 +doc-asciidoctorj is now url-asciidoctorj-docs but! that means I need to fix docref: link:/docs and doc-asciidoctorj: {docref}/asciidoctorj +//// + +In addition to its CLI, Asciidoctor provides a Ruby API. +The API is intended for integration with other software projects and is suitable for server-side applications, such as Rails, Sinatra and GitHub. + +Asciidoctor also has a Java API that mirrors the Ruby API. +The Java API calls through to the Ruby API using an embedded JRuby runtime. +See the AsciidoctorJ documentation for more information. + +== Load and convert a document using the API + +To use Asciidoctor in your application, you first need to require the gem: + +[source,ruby] +require 'asciidoctor' + +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 to load or convert AsciiDoc documents, which we'll cover on this page. + +To parse a file into an `Asciidoctor::Document` object: + +[source,ruby] +doc = Asciidoctor.load_file 'my-sample.adoc' + +You can get information about the document: + +[source,ruby] +puts doc.doctitle +puts doc.attributes + +To convert a file containing AsciiDoc markup to HTML 5, use: + +[source,ruby] +Asciidoctor.convert_file 'my-sample.adoc' + +The command will output to the file [.path]_my-sample.html_ in the same directory. + +You can convert the file to DocBook 5.0 by setting the `:backend` option to `'docbook'`: + +[source,ruby] +Asciidoctor.convert_file 'my-sample.adoc', backend: 'docbook' + +The command will output to the file [.path]_my-sample.xml_ in the same directory. diff --git a/docs/modules/api/pages/load-templates.adoc b/docs/modules/api/pages/load-templates.adoc new file mode 100644 index 00000000..487ecd57 --- /dev/null +++ b/docs/modules/api/pages/load-templates.adoc @@ -0,0 +1,24 @@ += Load Custom Templates +:url-tilt: https://github.com/rtomayko/tilt +:url-tests: {url-org}/asciidoctor/tree/master/test + +Asciidoctor allows you to override the converter methods used to convert almost any individual AsciiDoc element. +If you provide a directory of {url-tilt}[Tilt^]-compatible templates, named in such a way that Asciidoctor can figure out which template goes with which element, Asciidoctor will use the templates in this directory instead of its built-in templates for any elements for which it finds a matching template. +It will fallback to its default templates for everything else. + +[source,ruby] +---- +puts Asciidoctor.convert '*This* is Asciidoctor.', :header_footer => true, + :template_dir => 'templates' +---- + +The Document and Section templates should begin with `document` and `section`, respectively. +The file extension is used by Tilt to determine which view framework it will use to use to interpret the template. +For instance, if you want to write the template in ERB, you'd name these two templates `document.html.erb` and `section.html.erb`. +The first file extension, `.html`, maps to the converter and the second, `.erb` maps to the template engine. +To use Haml as the template engine, you'd name the templates `document.html.haml` and `section.html.haml`. + +Templates for block elements, like a paragraph or sidebar, are named after the block they handle. +For instance, to override the default paragraph template with an ERB template, put a file named `paragraph.html.erb` in the template directory you pass to the `Document` constructor using the `:template_dir` option. + +For more usage examples, see the {url-tests}[test suite^]. diff --git a/docs/modules/api/pages/options.adoc b/docs/modules/api/pages/options.adoc new file mode 100644 index 00000000..5a498567 --- /dev/null +++ b/docs/modules/api/pages/options.adoc @@ -0,0 +1,165 @@ += API Options + +[cols="15m,15,15,15,15"] +|=== +|Name |Description |Default value |Allowed values |CLI equivalent + +|: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. +|_not set_ +|Any number of #builtin-attributes,built-in# or user-defined attributes in one of the following formats: + +Hash: + +`{'name'\=>'value'}` + +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` + +|: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. +|file path +|`-B`, `--base-dir` + +|:catalog_assets +|If true, tells the parser to capture 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_ + +|: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 +|Sets the document type. +|article +|article, book, manpage, inline +|`-d`, `--doctype` + +|:eruby +|Specifies the eRuby implementation to use for executing the converter templates written in ERB. +|erb +|erb, erubis +|`-e`, `--eruby` + +|: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 +|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_ + +|: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 +|_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 +|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.* +|_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` + +|: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_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_ + +|: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`). +|_not set_ +|true, file path +|`-o`, `--out-file` + +|: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` +|=== diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc new file mode 100644 index 00000000..dcf13af6 --- /dev/null +++ b/docs/modules/api/pages/set-safe-mode.adoc @@ -0,0 +1,18 @@ += Set the Safe Mode Using the API +:navtitle: Set Safe Mode + +The default xref:ROOT:safe-modes.adoc[safe mode] in the API is `SECURE`. +You can change the safe mode using a string, symbol or integer value. +The value must be set in the document constructor using the `:safe` option. + + result = Asciidoctor.convert_file('master.adoc', :safe => 'server') + +or + + result = Asciidoctor.convert_file('master.adoc', :safe => :server) + +or + + result = Asciidoctor.convert_file('master.adoc', :safe => 10) + +You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode]. -- cgit v1.2.3 From a313298c205b18b9e2c71926401f50146a3bccc5 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Thu, 19 Nov 2020 01:17:31 -0700 Subject: add :standalone option to Ruby API options; list :header_footer as deprecated alias --- docs/modules/api/pages/convert-strings.adoc | 14 +++++++------- docs/modules/api/pages/load-templates.adoc | 4 ++-- docs/modules/api/pages/options.adoc | 11 +++++++---- 3 files changed, 16 insertions(+), 13 deletions(-) (limited to 'docs/modules/api') 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` -- cgit v1.2.3 From 64ec52d2dacb0ff9c5e54ff47bc35f56a67b18ea Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 19 Nov 2020 15:45:59 -0700 Subject: create integration modules; update stylesheet pages --- docs/modules/api/pages/set-safe-mode.adoc | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'docs/modules/api') diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc index dcf13af6..8ff65b5d 100644 --- a/docs/modules/api/pages/set-safe-mode.adoc +++ b/docs/modules/api/pages/set-safe-mode.adoc @@ -3,6 +3,9 @@ The default xref:ROOT:safe-modes.adoc[safe mode] in the API is `SECURE`. You can change the safe mode using a string, symbol or integer value. + +== Set :safe option + The value must be set in the document constructor using the `:safe` option. result = Asciidoctor.convert_file('master.adoc', :safe => 'server') @@ -15,4 +18,4 @@ or result = Asciidoctor.convert_file('master.adoc', :safe => 10) -You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode]. +You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. -- cgit v1.2.3 From a90f36363994f51fd5bb142942608e9dd7b8dd25 Mon Sep 17 00:00:00 2001 From: Dan Allen Date: Mon, 30 Nov 2020 18:25:25 -0700 Subject: use Ruby 2 hash syntax in examples --- docs/modules/api/pages/convert-strings.adoc | 2 +- docs/modules/api/pages/set-safe-mode.adoc | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) (limited to 'docs/modules/api') diff --git a/docs/modules/api/pages/convert-strings.adoc b/docs/modules/api/pages/convert-strings.adoc index 6eec4faf..71577c74 100644 --- a/docs/modules/api/pages/convert-strings.adoc +++ b/docs/modules/api/pages/convert-strings.adoc @@ -73,7 +73,7 @@ If you only want the inline markup to be returned, set the `:doctype` option to [source,ruby] ---- -puts Asciidoctor.convert '*This* is Asciidoctor.', :doctype => 'inline' +puts Asciidoctor.convert '*This* is Asciidoctor.', doctype: 'inline' ---- In this mode, Asciidoctor will only process the first block (e.g., paragraph) in the document and ignore the rest. diff --git a/docs/modules/api/pages/set-safe-mode.adoc b/docs/modules/api/pages/set-safe-mode.adoc index 8ff65b5d..eca166a3 100644 --- a/docs/modules/api/pages/set-safe-mode.adoc +++ b/docs/modules/api/pages/set-safe-mode.adoc @@ -8,14 +8,14 @@ You can change the safe mode using a string, symbol or integer value. The value must be set in the document constructor using the `:safe` option. - result = Asciidoctor.convert_file('master.adoc', :safe => 'server') + result = Asciidoctor.convert_file('master.adoc', safe: 'server') or - result = Asciidoctor.convert_file('master.adoc', :safe => :server) + result = Asciidoctor.convert_file('master.adoc', safe: :server) or - result = Asciidoctor.convert_file('master.adoc', :safe => 10) + result = Asciidoctor.convert_file('master.adoc', safe: 10) You can also set the xref:cli:set-safe-mode.adoc[safe mode from the CLI] and xref:ROOT:reference-safe-mode.adoc[enable or disable content based on the current safe mode]. -- cgit v1.2.3 From 062ddfe40c7b90205b74d1313969cd3287be99fe Mon Sep 17 00:00:00 2001 From: Sarah White Date: Thu, 3 Dec 2020 17:30:34 -0700 Subject: content clarifications, syntax fixes, and added xrefs --- docs/modules/api/pages/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/modules/api') diff --git a/docs/modules/api/pages/index.adoc b/docs/modules/api/pages/index.adoc index 5c909faa..6a53b4b1 100644 --- a/docs/modules/api/pages/index.adoc +++ b/docs/modules/api/pages/index.adoc @@ -20,7 +20,7 @@ To use Asciidoctor in your application, you first need to require the gem: [source,ruby] require 'asciidoctor' -This one statement makes all of the {url-api}[public APIs in Asciidoctor] available to your script or application. +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 to load or convert AsciiDoc documents, which we'll cover on this page. -- cgit v1.2.3 From 6dc7d871ab6c396071cb51ed3e3e8b1d349c6a47 Mon Sep 17 00:00:00 2001 From: Sarah White Date: Fri, 4 Dec 2020 12:51:34 -0700 Subject: clean up API options table and add xrefs --- docs/modules/api/pages/options.adoc | 183 ++++++++++++++++-------------------- 1 file changed, 79 insertions(+), 104 deletions(-) (limited to 'docs/modules/api') 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 |=== -- cgit v1.2.3