rearchitect modules and filenames and drop asciidoctor folder under docs

6 files changed, 321 insertions, 0 deletions

diff --git a/docs/modules/cli/pages/index.adoc b/docs/modules/cli/pages/index.adoc
new file mode 100644
index 00000000..6451af8c
--- /dev/null
+++ b/docs/modules/cli/pages/index.adoc
@@ -0,0 +1,32 @@
+= Process AsciiDoc Using the CLI
+:url-manpage: https://github.com/asciidoctor/asciidoctor/blob/master/man/asciidoctor.adoc
+
+////
+command-line-usage.adoc
+Command line usage quick start for Asciidoctor
+included in the install-toolchain and user-manual documents
+////
+
+When the Asciidoctor gem is installed successfully, the Asciidoctor command line interface (CLI) will be available on your PATH.
+To confirm that Asciidoctor is available, execute:
+
+ $ asciidoctor --version
+
+The following information should be output in your terminal:
+
+[subs=attributes+]
+ Asciidoctor {release-version} [https://asciidoctor.org]
+
+To invoke Asciidoctor from the CLI and convert an `.adoc` file, execute:
+
+ $ asciidoctor <asciidoc-file>
+
+This will use the built-in defaults for options and create a new file in the same directory as the input file, with the same base name, but with the `.html` extension.
+
+The xref:options.adoc[] describes the available Asciidoctor CLI options and parameters.
+
+Full help is provided in the {url-manpage}[Asciidoctor man page^] or via:
+
+ $ asciidoctor --help
+
+//There is also an `asciidoctor-safe` command, which turns on safe mode by default, preventing access to files outside the parent directory of the source file.
diff --git a/docs/modules/cli/pages/io-piping.adoc b/docs/modules/cli/pages/io-piping.adoc
new file mode 100644
index 00000000..9b9eb5ce
--- /dev/null
+++ b/docs/modules/cli/pages/io-piping.adoc
@@ -0,0 +1,45 @@
+= Pipe Content Through the CLI
+
+In addition to converting files, the Asciidoctor CLI can read content from standard input (STDIN) and/or write content to standard output (STDOUT).
+This feature is called piping.
+
+Using the `-` flag, you can pipe content to the `asciidoctor` command.
+This flag tells Asciidoctor read the source from standard input (STDIN).
+For example:
+
+ $ echo 'content' | asciidoctor -
+
+NOTE: Any variation of STDIN will work.
+
+This command is effectively the same as:
+
+ $ echo 'content' | asciidoctor -o - -
+
+When reading source from STDIN, Asciidoctor doesn't have a reference to an input file.
+Therefore, it sends the converted text to standard output (STDOUT) by default.
+
+If, instead, you want to write the full document to an output file, you specify it using the `-o` flag.
+For example, the following command writes a standalone HTML document to [.path]_output.html_ instead of STDOUT:
+
+ $ echo 'content' | asciidoctor -o output.html -
+
+When you pipe content to the `asciidoctor` command, it no longer has a concept of where the document is located.
+Therefore, relative references such as includes may not work as expected.
+To resolve this problem, you should specify an absolute base directory using the `-B` option:
+
+ $ echo 'content' | asciidoctor -B /path/to/basedir -o output.html -
+
+Alternately, you can set an artificial document directory by passing an absolute path to the `docdir` attribute:
+
+ $ echo 'content' | asciidoctor -a docdir=/path/to/docdir -o output.html -
+
+Try both approaches to determine which one suits your needs better.
+
+When piping source from STDIN to STDOUT through the `asciidoctor` command, you often just want the converted body (i.e., embeddable HTML).
+To produce that variant, add the `-s` flag:
+
+ $ echo 'content' | asciidoctor -s -
+
+Or perhaps you want to include the doctitle as well:
+
+ $ echo -e '= Document Title\n\ncontent' | asciidoctor -s -a showtitle -
diff --git a/docs/modules/cli/pages/options.adoc b/docs/modules/cli/pages/options.adoc
new file mode 100644
index 00000000..4c4a2236
--- /dev/null
+++ b/docs/modules/cli/pages/options.adoc
@@ -0,0 +1,138 @@
+= CLI Options
+// um anchor: appendix#cli-options
+// DO NOT EDIT THIS FILE
+// Copy the content from asciidoctor/man/asciidoctor.adoc
+
+== Security Settings
+
+*-B, --base-dir*=_DIR_::
+  Base directory containing the document and resources.
+  Defaults to the directory containing the source file or, if the source is read from a stream, the working directory.
+  When combined with the safe mode setting, can be used to chroot the execution of the program.
+
+*-S, --safe-mode*=_SAFE_MODE_::
+  Set safe mode level: _unsafe_, _safe_, _server_, or _secure_.
+  Disables potentially dangerous macros in source files, such as `include::[]`.
+  If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script.
+
+*--safe*::
+  Set safe mode level to _safe_.
+  Enables include directives, but prevents access to ancestor paths of source file.
+  Provided for compatibility with the asciidoc command.
+  If not set, the safe mode level defaults to _unsafe_ when Asciidoctor is invoked using this script.
+
+== Document Settings
+
+*-a, --attribute*=_ATTRIBUTE_::
+  Define, override, or unset a document attribute.
+  Command-line attributes take precedence over attributes defined in the source file unless either the name or value ends in _@_.
++
+_ATTRIBUTE_ is normally formatted as a key-value pair, in the form _NAME=VALUE_.
+Alternate forms are _NAME_ (where the _VALUE_ defaults to an empty string), _NAME!_ (unsets the _NAME_ attribute), and _NAME=VALUE@_ (or _NAME@=VALUE_) (where _VALUE_ does not override the _NAME_ attribute if it's already defined in the source document).
+Values containing spaces should be enclosed in quotes.
++
+This option may be specified more than once.
+
+*-b, --backend*=_BACKEND_::
+  Backend output file format: _html5_, _docbook5_, and _manpage_ are supported out of the box.
+  You can also use the backend alias names _html_ (aliased to _html5_) or _docbook_ (aliased to _docbook5_).
+  Other values can be passed, but if Asciidoctor cannot resolve the backend to a converter, it will fail.
+  Defaults to _html5_.
+
+*-d, --doctype*=_DOCTYPE_::
+  Document type: _article_, _book_, _manpage_, or _inline_.
+  Sets the root element when using the _docbook_ backend and the style class on the HTML body element when using the _html_ backend.
+  The _book_ document type allows multiple level-0 section titles in a single document.
+  The _manpage_ document type enables parsing of metadata necessary to produce a man page.
+  The _inline_ document type allows the content of a single paragraph to be formatted and returned without wrapping it in a containing element.
+  Defaults to _article_.
+
+== Document Conversion
+
+*-D, --destination-dir*=_DIR_::
+  Destination output directory.
+  Defaults to the directory containing the source file or, if the source is read from a stream, the working directory.
+  If specified, the directory is resolved relative to the working directory.
+
+*-E, --template-engine*=_NAME_::
+  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.
+  If a template engine is not specified, it will be auto-detected based on the file extension of the custom converter templates found.
+
+*-e, --eruby*::
+  Specifies the eRuby implementation to use for executing the custom converter templates written in ERB.
+  Supported values are _erb_ and _erubis_.
+  Defaults to _erb_.
+
+*-I, --load-path*=_DIRECTORY_::
+  Add the specified directory to the load path, so that _-r_ can load extensions from outside the default Ruby load path.
+  This option may be specified more than once.
+
+*-n, --section-numbers*::
+  Auto-number section titles.
+  Synonym for *--attribute sectnums*.
+
+*-o, --out-file*=_OUT_FILE_::
+  Write output to file _OUT_FILE_.
+  Defaults to the base name of the input file suffixed with _backend_ extension.
+  The file is resolved relative to the working directory.
+  If the input is read from standard input or a named pipe (fifo), then the output file defaults to stdout.
+  If _OUT_FILE_ is _-_, then the output file is written to standard output.
+
+*-R, --source-dir*=_DIR_::
+  Source directory.
+  Currently only used if the destination directory is also specified.
+  Used to preserve the directory structure of files converted within this directory in the destination directory.
+  If specified, the directory is resolved relative to the working directory.
+
+*-r, --require*=_LIBRARY_::
+  Require the specified library before executing the processor, using the standard Ruby require.
+  This option may be specified more than once.
+
+*-s, --no-header-footer*::
+  Output an embeddable document, which excludes the header, the footer, and everything outside the body of the document.
+  This option is useful for producing documents that can be inserted into an external template.
+
+*-T, --template-dir*=_DIR_::
+  A directory containing custom converter templates that override one or more templates from the built-in set.
+  (requires _tilt_ gem)
++
+If there is a subfolder that matches the engine name (if specified), that folder is appended to the template directory path.
+Similarly, if there is a subfolder in the resulting template directory that matches the name of the backend, that folder is appended to the template directory path.
++
+This option may be specified more than once.
+Matching templates found in subsequent directories override ones previously discovered.
+
+== Processing Information
+
+*--failure-level*=_LEVEL_::
+  The minimum logging level that triggers a non-zero exit code (failure).
+  If this option is not set (default: FATAL), the program exits with exit code zero even if warnings or errors have been logged.
+
+*-q, --quiet*::
+  Silence application log messages and script warnings.
+
+*--trace*::
+  Include backtrace information when reporting errors.
+
+*-v, --verbose*::
+  Verbosely print processing information to stderr, including debug-level log messages.
+
+*-w, --warnings*::
+  Turn on script warnings (applies to executed code).
+
+*-t, --timings*::
+  Print timings report to stderr (time to read, parse, and convert).
+
+== Program Information
+
+*-h, --help* [_TOPIC_]::
+  Print a help message.
+  Show the command usage if _TOPIC_ is not specified or recognized.
+  Dump the Asciidoctor man page (in troff/groff format) if _TOPIC_ is _manpage_.
+
+*-V, --version*::
+  Print program version number.
++
+*-v* can also be used if no source files are specified.
diff --git a/docs/modules/cli/pages/output-file.adoc b/docs/modules/cli/pages/output-file.adoc
new file mode 100644
index 00000000..5867a201
--- /dev/null
+++ b/docs/modules/cli/pages/output-file.adoc
@@ -0,0 +1,39 @@
+= Specify an Output File
+// Included in user-manual: Specifying an output file
+
+By default, the Asciidoctor CLI writes the converted output file to the same directory as the input file.
+If an output file is not specified, the name of the output file is derived from the input file by replacing its file extension with the file extension that matches the output format (e.g., replacing .adoc with .html).
+
+You can instruct the Asciidoctor CLI to write content to a different output file (or directory).
+There are several circumstances when you'll want to specify a different output file:
+
+* You want to write the output file to a different name, perhaps to append a qualifier such as a version string.
+* You want to write the output file to a different directory.
+* You are piping content to the CLI, but want to write the output to a file (in this case, an output file is required).
+
+CAUTION: If you specify the output file as a relative path, it will be resolved relative to the current working directory instead of the directory of the input file (i.e., specifying the output file implicitly sets the output directory too).
+
+To specify the output file, you'll use the `-o` option.
+For example, let's say we want to convert [.path]_mydoc.adoc_ and write the output to a filename that includes the current date.
+You'd use:
+
+ $ asciidoctor -o mydoc-$(date +%Y-%m-%d).html mydoc.adoc
+
+We could write it to another folder as well by prefixing the output file with a folder name:
+
+ $ asciidoctor -o build/mydoc-$(date +%Y-%m-%d).html mydoc.adoc
+
+If you only want to specify the output directory, but let the filename be defaulted, use the `-D` option:
+
+ $ asciidoctor -D build mydoc.adoc
+
+The `-D` option can also be used when processing multiple input files:
+
+ $ asciidoctor -D build *.adoc
+
+If you are piping content to the CLI, the default is to write the output to STDOUT.
+If you want to write the output to a file in this case, you have to specify one:
+
+ $ cat mydoc.adoc | asciidoctor -o build/mydoc-$(date +%Y-%m-%d).html -
+
+See xref:io-piping.adoc[] to learn more.
diff --git a/docs/modules/cli/pages/process-multiple-files.adoc b/docs/modules/cli/pages/process-multiple-files.adoc
new file mode 100644
index 00000000..0d565b77
--- /dev/null
+++ b/docs/modules/cli/pages/process-multiple-files.adoc
@@ -0,0 +1,48 @@
+= Process Multiple Source Files
+
+The Asciidoctor CLI can convert multiple files in a single invocation.
+If you pass multiple source filenames or a filename pattern to the CLI, Asciidoctor will convert each file in turn.
+
+Let's assume there exist two AsciiDoc files in the current directory, [.path]_a.adoc_ and [.path]_b.adoc_.
+You can pass both files to Asciidoctor using a single command, as follows:
+
+ $ asciidoctor a.adoc b.adoc
+
+Asciidoctor will convert both files, transforming [.path]_a.adoc_ to [.path]_a.html_ and [.path]_b.adoc_ to [.path]_b.html_.
+
+To save some typing, you can use the glob operator (`+*+`) to match all AsciiDoc files in the current directory using a single argument:
+
+ $ asciidoctor *.adoc
+
+Your shell will automatically expand the pattern and interpret the command exactly as you had typed it above:
+
+ $ asciidoctor a.adoc b.adoc
+
+You can pass all AsciiDoc files inside direct subfolders using the glob operator (`+*+`) in place of the directory name:
+
+ $ asciidoctor */*.adoc
+
+To match all files in the current directory and direct subfolders, combine both glob patterns:
+
+ $ asciidoctor *.adoc */*.adoc
+
+Since the globs in this command rely on shell expansion, the command is not portable across platforms.
+To make it portable, you can allow the Asciidoctor CLI to expand the globs.
+To do so, instruct the shell to not expand the glob by quoting the pattern, as shown here:
+
+ $ asciidoctor '*.adoc' '*/*.adoc'
+
+This time, the arguments `+*.adoc+` and `+*/*.adoc+` are passed directly to Asciidoctor instead of being expanded.
+Asciidoctor handles the glob matching in a manner that is portable across platforms.
+
+But it gets better.
+The glob handling in Asciidoctor (which matches the rules of file globbing in Ruby) is likely more powerful than what your shell offers.
+For example, you can match AsciiDoc files in the current folder and in folders of any depth using the double glob operator (`+**+`).
+
+ $ asciidoctor '**/*.adoc'
+
+Most shells do not honor this double glob pattern.
+
+In conclusion, when specifying a glob pattern, we always recommend enclosing the argument in quotes.
+
+CAUTION: To process multiple nested AsciiDoc files at once and apply a custom stylesheet, you'll need to xref:html-backend:apply-stylesheet.adoc#style-nested[manage the stylesheet's location].
diff --git a/docs/modules/cli/pages/set-safe-mode.adoc b/docs/modules/cli/pages/set-safe-mode.adoc
new file mode 100644
index 00000000..31110060
--- /dev/null
+++ b/docs/modules/cli/pages/set-safe-mode.adoc
@@ -0,0 +1,19 @@
+= Set the Safe Mode Using the CLI
+:navtitle: Set the Safe Mode
+
+When Asciidoctor is invoked via the CLI, the xref:ROOT:safe-modes.adoc[safe mode] is set to `UNSAFE` by default.
+You can change the security level by executing one of the following commands:
+
+`-S`, `--safe-mode=SAFE_MODE`::
+Sets the safe mode level of the document according to the assigned level (`UNSAFE`, `SAFE`, `SERVER`, `SECURE`).
+
+`--safe`, `asciidoctor-safe`::
+Sets the safe mode level to `SAFE`.
+Provided for compatibility with the python AsciiDoc `safe` command.
+
+////
+-B, --base-dir=DIR
+Base directory containing the document and resources. Defaults to the directory containing the source file, or the working directory if the source is read from a stream. Can be used as a way to chroot the execution of the program.
+////
+
+You can also set the xref:api:set-safe-mode.adoc[safe mode from the API] and xref:ROOT:attributes-and-safe-modes.adoc[manage attributes by safe mode].